@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

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

@@ -0,0 +1,175 @@
+import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
+import { type ClaustrumLogger } from './errors.js';
+export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'>;
+/** The two credential types a plugin's family can hold; routing differs by type. */
+export type VaultCredentialType = 'oauth' | 'api_key';
+/**
+ * Which vault rows belong to this plugin. `refreshAdapter` classifies an OAuth
+ * row by the protocol it speaks; `category` is the grant that authorizes this
+ * consumer to read it. Static API keys carry no refresh adapter, so they are
+ * admitted only when `apiKeys` is set and only by category.
+ */
+export interface ClaustrumFamily {
+    refreshAdapter: string;
+    category: string;
+    apiKeys?: boolean;
+}
+/** One vault credential this consumer may serve. Never carries bearer material. */
+export interface VaultCredential {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    /**
+     * The provider account the credential logs into, when the vault's adapter
+     * claims one. Absent means the adapter makes no claim, not a mismatch.
+     */
+    readonly accountIdentity?: string;
+    readonly state: string;
+    readonly email?: string;
+    readonly orgName?: string;
+}
+/**
+ * Why a listed vault record could not be used. A closed set of fixed codes, so
+ * a log line or a roster file that carries one never echoes vault data.
+ */
+export type SkippedVaultReason = 'empty credential id' | 'duplicate credential id' | 'blank account identity' | 'empty state';
+/**
+ * A vault record this consumer could not use. `credentialId` is absent when
+ * the record's id itself was unusable, so nothing can say which account the
+ * record was.
+ */
+export interface SkippedVaultRecord {
+    readonly credentialId?: string;
+    readonly reason: SkippedVaultReason;
+}
+export interface VaultInventory {
+    /**
+     * The vault's change cursor: a digest over exactly what this consumer can see
+     * (ids, grants, state, identity), never over record versions, so a routine
+     * token refresh does not move it. Only equality is meaningful.
+     */
+    readonly view: string;
+    readonly credentials: readonly VaultCredential[];
+    readonly skipped: readonly SkippedVaultRecord[];
+}
+export interface ClaustrumScopedIdentity {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    readonly accountIdentity?: string;
+}
+/**
+ * Where a receipt's `accountIdentity` came from: the vault asserted it in the
+ * served reply, the plugin's `parseIdentity` read it from the served token, or
+ * neither did and it is only the roster's expectation (`none`: no identity at
+ * all).
+ */
+export type AccountIdentitySource = 'asserted' | 'parsed' | 'expected' | 'none';
+/**
+ * A receipt: what the vault served for one physical send. Each attempt gets
+ * its own. It records the exact record version served, because a 401 for
+ * this send is reported to the vault against that version.
+ */
+export interface ClaustrumScopedAttempt {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    /**
+     * The account this receipt is bound to: the vault's assertion, else the
+     * plugin's parse of the token, else the roster's expectation. Check
+     * `accountIdentitySource` before treating it as proof.
+     */
+    readonly accountIdentity?: string;
+    readonly accountIdentitySource: AccountIdentitySource;
+    /** The account the roster row named when this receipt was requested. */
+    readonly expectedAccountIdentity?: string;
+    /** The credential id the vault itself put in the served reply, if any. */
+    readonly assertedCredentialId?: string;
+    /**
+     * The account the vault itself put in the served reply, if any. Never filled
+     * in from the roster or from a token parse.
+     */
+    readonly assertedAccountIdentity?: string;
+    /**
+     * The non-secret Google Cloud project id the vault served in get_scoped for
+     * this attempt, if any. Never filled in from list_scoped, the roster or a
+     * token parse. A project change in the vault takes effect on the next send.
+     */
+    readonly projectId?: string;
+    /**
+     * Kept in memory only and hidden from JSON.stringify and object spreads, so
+     * logging a receipt never leaks it. Authorize again for every dispatch and retry.
+     */
+    readonly accessToken: string;
+    readonly recordVersion: number;
+    readonly expiresAtMs: number | null;
+}
+/** Reads the provider identity a served token executes under, when the plugin can tell. */
+export type IdentityParser = (accessToken: string) => string | undefined;
+/** Only a new version of the same account may replace an in-flight 401. */
+export declare function isScopedCredentialRotation(served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined): current is ClaustrumScopedAttempt;
+/** Why a scoped 401 did or did not retry. Never carries credential material. */
+export type ScopedRetryReason = 'rotated' | 'reauthorize-failed' | 'credential-changed' | 'account-changed' | 'version-unchanged';
+/**
+ * Decide whether a request that got a 401 should retry with the freshly
+ * re-authorized receipt, and log the decision. The vault can refresh a
+ * credential between the send and the 401; the log line lets that refresh be
+ * matched against the consumer's retry. `site` names the kind of request.
+ */
+export declare function decideScopedRetryAfter401(site: string, served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined, logger?: ClaustrumLogger): current is ClaustrumScopedAttempt;
+/**
+ * How long a served OAuth token must stay valid after the vault hands it out,
+ * so it cannot expire while a long request is still using it.
+ */
+export declare const SERVING_MARGIN_MS = 300000;
+/**
+ * Reads this consumer's vault credentials (list, fetch, 401 report), with the
+ * enrollment token as authorization. Used by every host of a plugin. There is
+ * deliberately no credential cache and no single-flight of credential reads:
+ * each physical send is authorized by the vault, so a revoked enrollment or a
+ * changed record takes effect on the next send. The enrollment token is
+ * re-read per operation so an operator's reissue on disk is picked up.
+ */
+export declare class ClaustrumScopedCustody {
+    #private;
+    constructor(options: {
+        client: ClaustrumScopedClient;
+        family: ClaustrumFamily;
+        tokenPath?: string;
+        readToken?: () => Promise<EnrollmentTokenFile>;
+        parseIdentity?: IdentityParser;
+        /**
+         * Issue a receipt only when the vault's served reply itself names the
+         * requested credential id and the roster's (known) account identity. For
+         * providers whose tokens are opaque, where nothing else can prove which
+         * account a token belongs to. Off by default: then an absent assertion is
+         * no claim, and the receipt says where its identity came from.
+         */
+        requireAssertion?: boolean;
+        now?: () => number;
+        logger?: ClaustrumLogger;
+    });
+    /**
+     * List this consumer's credentials. A record that cannot be used is skipped
+     * and warned about rather than failing the whole list, so one bad record
+     * never hides every other account. Records outside the family are not
+     * skipped records: they simply are not this consumer's.
+     */
+    discover(signal?: AbortSignal): Promise<VaultInventory>;
+    /**
+     * Fetch the credential for one physical send and wrap it in a fresh receipt.
+     * The vault's served identity (or, without one, the plugin's parse of the
+     * token) must equal the roster's when both are present. Without
+     * `requireAssertion`, absence on either side proves nothing and does not
+     * refuse; the receipt records what the vault asserted separately from what
+     * the roster expected. With it, a reply that does not itself name the
+     * credential id and the expected account is refused.
+     */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    /**
+     * Report that a send this consumer actually made was rejected. Only a 401
+     * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
+     * credential id with the exact record version that send was served, and
+     * signed with the enrollment token that authorized it. A receipt this
+     * custody did not issue is refused rather than reported.
+     */
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    close(): void;
+}

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

@@ -0,0 +1,354 @@
+import { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
+import { createLogger } from '../logger/index.js';
+import { readClaustrumEnrollmentToken } from './enrollment.js';
+import { ClaustrumConsumerError } from './errors.js';
+import { CUSTODY_PLACEHOLDER_PREFIX } from './host-slot.js';
+/** Only a new version of the same account may replace an in-flight 401. */
+export function isScopedCredentialRotation(served, current) {
+    return (current !== undefined &&
+        current.credentialId === served.credentialId &&
+        current.accountIdentity === served.accountIdentity &&
+        current.recordVersion !== served.recordVersion);
+}
+function scopedRetryReason(served, current) {
+    if (current === undefined)
+        return 'reauthorize-failed';
+    if (current.credentialId !== served.credentialId)
+        return 'credential-changed';
+    if (current.accountIdentity !== served.accountIdentity)
+        return 'account-changed';
+    if (current.recordVersion === served.recordVersion)
+        return 'version-unchanged';
+    return 'rotated';
+}
+const defaultLogger = createLogger('claustrum');
+/**
+ * Decide whether a request that got a 401 should retry with the freshly
+ * re-authorized receipt, and log the decision. The vault can refresh a
+ * credential between the send and the 401; the log line lets that refresh be
+ * matched against the consumer's retry. `site` names the kind of request.
+ */
+export function decideScopedRetryAfter401(site, served, current, logger = defaultLogger) {
+    const retry = isScopedCredentialRotation(served, current);
+    logger.debug('scoped 401 re-authorized', {
+        site,
+        credentialId: served.credentialId,
+        servedVersion: served.recordVersion,
+        currentVersion: current?.recordVersion ?? null,
+        retry,
+        reason: scopedRetryReason(served, current),
+    });
+    return retry;
+}
+/**
+ * How long a served OAuth token must stay valid after the vault hands it out,
+ * so it cannot expire while a long request is still using it.
+ */
+export const SERVING_MARGIN_MS = 300_000;
+function invalidMaterial() {
+    return new ClaustrumConsumerError('invalid-material', 'Claustrum returned invalid credential material');
+}
+function accessTokenFromMaterial(material) {
+    let access = material.trim();
+    if (access.startsWith('{')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(access);
+        }
+        catch {
+            throw invalidMaterial();
+        }
+        if (!parsed || typeof parsed !== 'object')
+            throw invalidMaterial();
+        const record = parsed;
+        const value = record.access_token ?? record.access;
+        access = typeof value === 'string' ? value : '';
+    }
+    // A header-safe token only: control characters could split the request,
+    // and the custody placeholder must never be sent as a credential.
+    if (!/^[\x21-\x7e]+$/.test(access) ||
+        access.startsWith(CUSTODY_PLACEHOLDER_PREFIX)) {
+        throw invalidMaterial();
+    }
+    return access;
+}
+function credentialTypeOf(row, family) {
+    if (!row.operations.includes('read'))
+        return undefined;
+    if (!row.categories.includes(family.category))
+        return undefined;
+    if (row.credentialType === 'oauth')
+        return row.refreshAdapter === family.refreshAdapter ? 'oauth' : undefined;
+    if (row.credentialType === 'api_key' && family.apiKeys)
+        return row.refreshAdapter === undefined ? 'api_key' : undefined;
+    return undefined;
+}
+/**
+ * Reads this consumer's vault credentials (list, fetch, 401 report), with the
+ * enrollment token as authorization. Used by every host of a plugin. There is
+ * deliberately no credential cache and no single-flight of credential reads:
+ * each physical send is authorized by the vault, so a revoked enrollment or a
+ * changed record takes effect on the next send. The enrollment token is
+ * re-read per operation so an operator's reissue on disk is picked up.
+ */
+export class ClaustrumScopedCustody {
+    #client;
+    #readToken;
+    #now;
+    #family;
+    #parseIdentity;
+    #requireAssertion;
+    #logger;
+    #provenance = new WeakMap();
+    #reports = new WeakMap();
+    #closed = false;
+    constructor(options) {
+        const tokenPath = options.tokenPath;
+        if (options.readToken) {
+            this.#readToken = options.readToken;
+        }
+        else if (tokenPath) {
+            this.#readToken = () => readClaustrumEnrollmentToken(tokenPath);
+        }
+        else {
+            throw new ClaustrumConsumerError('not-enrolled', 'Claustrum enrollment token path is required');
+        }
+        this.#client = options.client;
+        this.#family = options.family;
+        this.#parseIdentity = options.parseIdentity;
+        this.#requireAssertion = options.requireAssertion ?? false;
+        this.#now = options.now ?? Date.now;
+        this.#logger = options.logger ?? defaultLogger;
+    }
+    #check(signal) {
+        if (this.#closed)
+            throw new ClaustrumConsumerError('closed', 'Claustrum scoped custody is closed');
+        signal?.throwIfAborted();
+    }
+    async #token(signal) {
+        this.#check(signal);
+        const value = await this.#readToken();
+        this.#check(signal);
+        if (!/^[0-9a-f]{64}$/.test(value.token) ||
+            !Number.isSafeInteger(value.token_generation) ||
+            value.token_generation < 1) {
+            throw new ClaustrumConsumerError('invalid-token', 'Invalid Claustrum enrollment token');
+        }
+        return value.token;
+    }
+    async #call(operation, signal) {
+        this.#check(signal);
+        let result;
+        let removeAbortListener;
+        try {
+            const pending = operation();
+            result = signal
+                ? await Promise.race([
+                    pending,
+                    new Promise((_resolve, reject) => {
+                        const abort = () => reject(signal.reason);
+                        signal.addEventListener('abort', abort, { once: true });
+                        removeAbortListener = () => signal.removeEventListener('abort', abort);
+                        if (signal.aborted)
+                            abort();
+                    }),
+                ])
+                : await pending;
+        }
+        catch (error) {
+            this.#check(signal);
+            // Keep the vault's own refusals (ClaustrumCredentialError, carrying
+            // code, class and action); replace any other error, whose text may echo
+            // request params that include the enrollment token.
+            if (error instanceof ClaustrumCredentialError)
+                throw error;
+            throw new ClaustrumConsumerError('unavailable', 'Claustrum scoped operation unavailable');
+        }
+        finally {
+            removeAbortListener?.();
+        }
+        this.#check(signal);
+        return result;
+    }
+    /**
+     * List this consumer's credentials. A record that cannot be used is skipped
+     * and warned about rather than failing the whole list, so one bad record
+     * never hides every other account. Records outside the family are not
+     * skipped records: they simply are not this consumer's.
+     */
+    async discover(signal) {
+        const token = await this.#token(signal);
+        const inventory = await this.#call(() => this.#client.listScoped(token), signal);
+        const skipped = [];
+        const candidates = [];
+        const counts = new Map();
+        for (const row of inventory.rows) {
+            const type = credentialTypeOf(row, this.#family);
+            if (!type)
+                continue;
+            candidates.push({ row, type });
+            counts.set(row.id, (counts.get(row.id) ?? 0) + 1);
+        }
+        const credentials = [];
+        for (const { row, type } of candidates) {
+            let reason;
+            if (!row.id.trim())
+                reason = 'empty credential id';
+            else if ((counts.get(row.id) ?? 0) > 1)
+                reason = 'duplicate credential id';
+            else if (row.accountId !== undefined && !row.accountId.trim())
+                reason = 'blank account identity';
+            else if (!row.state.trim())
+                reason = 'empty state';
+            if (reason) {
+                skipped.push({ ...(row.id.trim() && { credentialId: row.id }), reason });
+                continue;
+            }
+            credentials.push(Object.freeze({
+                credentialId: row.id,
+                credentialType: type,
+                ...(row.accountId !== undefined && {
+                    accountIdentity: row.accountId,
+                }),
+                state: row.state,
+                ...(row.email !== undefined && { email: row.email }),
+                ...(row.orgName !== undefined && { orgName: row.orgName }),
+            }));
+        }
+        for (const record of skipped)
+            this.#logger.warn('skipped malformed vault record', record);
+        return {
+            view: inventory.view,
+            credentials: Object.freeze(credentials),
+            skipped: Object.freeze(skipped),
+        };
+    }
+    /**
+     * Fetch the credential for one physical send and wrap it in a fresh receipt.
+     * The vault's served identity (or, without one, the plugin's parse of the
+     * token) must equal the roster's when both are present. Without
+     * `requireAssertion`, absence on either side proves nothing and does not
+     * refuse; the receipt records what the vault asserted separately from what
+     * the roster expected. With it, a reply that does not itself name the
+     * credential id and the expected account is refused.
+     */
+    async authorize(identity, signal) {
+        if (!identity.credentialId)
+            throw new ClaustrumConsumerError('route-unavailable', 'Claustrum dispatch requires a credential id');
+        // Capture the caller's fields before yielding so a later mutation cannot move the fence.
+        const { credentialId, credentialType, accountIdentity } = identity;
+        if (this.#requireAssertion && accountIdentity === undefined)
+            throw new ClaustrumConsumerError('identity-unasserted', 'Claustrum dispatch requires a known account identity');
+        const token = await this.#token(signal);
+        const served = await this.#call(() => this.#client.getScoped({
+            credentialId,
+            enrollmentToken: token,
+            ...(credentialType === 'oauth' && { minTtlMs: SERVING_MARGIN_MS }),
+        }), signal);
+        if (served.credentialId !== undefined &&
+            served.credentialId !== credentialId) {
+            throw new ClaustrumConsumerError('identity-changed', 'Claustrum served credential identity changed');
+        }
+        const expiresAtMs = served.expiresAtMs;
+        if (!Number.isSafeInteger(served.recordVersion) ||
+            served.recordVersion < 0 ||
+            (expiresAtMs === null && credentialType === 'oauth') ||
+            (expiresAtMs !== null &&
+                (!Number.isFinite(expiresAtMs) ||
+                    expiresAtMs - this.#now() < SERVING_MARGIN_MS))) {
+            throw new ClaustrumConsumerError('insufficient-validity', 'Claustrum served credential has insufficient validity');
+        }
+        const accessToken = accessTokenFromMaterial(served.material);
+        const assertedIdentity = served.accountId?.trim()
+            ? served.accountId
+            : undefined;
+        if (this.#requireAssertion &&
+            (served.credentialId === undefined || assertedIdentity === undefined))
+            throw new ClaustrumConsumerError('identity-unasserted', 'Claustrum served credential did not assert its identity');
+        const parsedIdentity = assertedIdentity === undefined
+            ? this.#parseIdentity?.(accessToken)
+            : undefined;
+        const servedIdentity = assertedIdentity ?? parsedIdentity;
+        if (accountIdentity !== undefined &&
+            servedIdentity !== undefined &&
+            servedIdentity !== accountIdentity) {
+            throw new ClaustrumConsumerError('identity-changed', 'Claustrum served credential identity changed');
+        }
+        const resolvedIdentity = servedIdentity ?? accountIdentity;
+        const source = assertedIdentity !== undefined
+            ? 'asserted'
+            : parsedIdentity !== undefined
+                ? 'parsed'
+                : accountIdentity !== undefined
+                    ? 'expected'
+                    : 'none';
+        const attempt = Object.freeze(Object.defineProperty({
+            credentialId,
+            credentialType,
+            ...(resolvedIdentity !== undefined && {
+                accountIdentity: resolvedIdentity,
+            }),
+            accountIdentitySource: source,
+            ...(accountIdentity !== undefined && {
+                expectedAccountIdentity: accountIdentity,
+            }),
+            ...(served.credentialId !== undefined && {
+                assertedCredentialId: served.credentialId,
+            }),
+            ...(assertedIdentity !== undefined && {
+                assertedAccountIdentity: assertedIdentity,
+            }),
+            ...(served.projectId !== undefined && {
+                projectId: served.projectId,
+            }),
+            recordVersion: served.recordVersion,
+            expiresAtMs,
+        }, 'accessToken', { value: accessToken, enumerable: false }));
+        this.#provenance.set(attempt, token);
+        return attempt;
+    }
+    /**
+     * Report that a send this consumer actually made was rejected. Only a 401
+     * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
+     * credential id with the exact record version that send was served, and
+     * signed with the enrollment token that authorized it. A receipt this
+     * custody did not issue is refused rather than reported.
+     */
+    async reportFailure(attempt, status, reporterSource) {
+        if (status !== 401)
+            return;
+        this.#check();
+        const token = this.#provenance.get(attempt);
+        if (!token)
+            throw new ClaustrumConsumerError('no-receipt', 'Claustrum failure report requires an original dispatch receipt');
+        const pending = this.#reports.get(attempt);
+        if (pending)
+            return pending;
+        const report = this.#call(() => this.#client.reportAuthFailureScoped({
+            credentialId: attempt.credentialId,
+            enrollmentToken: token,
+            providerStatus: 401,
+            recordVersion: attempt.recordVersion,
+            reporterSource,
+        }));
+        this.#reports.set(attempt, report);
+        try {
+            await report;
+            this.#logger.debug('scoped 401 reported', {
+                credentialId: attempt.credentialId,
+                recordVersion: attempt.recordVersion,
+                reporterSource,
+            });
+        }
+        catch (error) {
+            this.#reports.delete(attempt);
+            throw error;
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#client.close();
+    }
+}

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

@@ -0,0 +1,158 @@
+import { type ClaustrumClientOptions as ClaustrumEnrollmentClientOptions, type EnrollmentPollOutcome, type EnrollmentTokenFile, writeEnrollmentTokenFile } from '@cortexkit/claustrum-client';
+/**
+ * Codes the vault's closed enrollment-refusal vocabulary marks permanent. The
+ * client labels some module error frames transient/retry regardless, so the
+ * producer's code takes precedence over the client's action for these.
+ */
+export declare const TERMINAL_ENROLLMENT_CODES: ReadonlySet<string>;
+/** Codes that are always worth another ceremony tick, whatever the action says. */
+export declare const RETRYABLE_ENROLLMENT_CODES: ReadonlySet<string>;
+export type EnrollmentDisposition = 'terminal' | 'retry';
+/**
+ * Classify an enrollment transport refusal as `(code, disposition)`. The
+ * vault's own code wins: a terminal code is terminal even when the client
+ * says retry, queue saturation is retryable even when it says gone, and any
+ * other code follows the client's action. Errors that are not producer
+ * refusals return undefined and are the caller's to rethrow.
+ */
+export declare function classifyEnrollmentError(error: unknown): {
+    code: string;
+    disposition: EnrollmentDisposition;
+} | undefined;
+/**
+ * The name a plugin proposes for one host, for example `openai-auth-opencode`.
+ * Each host enrolls separately so the operator can revoke one without the other.
+ */
+export declare function enrollmentName(plugin: string, host: string): string;
+export interface ClaustrumEnrollmentClient {
+    enrollPropose(input: {
+        name: string;
+        requestSecretHash: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    enrollPoll(input: {
+        requestId: string;
+        requestSecret: string;
+    }): Promise<EnrollmentPollOutcome>;
+}
+export interface ClaustrumEnrollmentConnection extends ClaustrumEnrollmentClient {
+    close(): void;
+}
+/**
+ * Connect the enrollment ceremony. Setup calls this; the request path never
+ * does. `connectionFile` is required because this library reads no
+ * environment and knows no host paths.
+ */
+export declare function connectClaustrumEnrollmentClient(options: ClaustrumEnrollmentClientOptions & {
+    connectionFile: string;
+}): Promise<ClaustrumEnrollmentConnection>;
+export type ClaustrumEnrollmentStatus = {
+    state: 'idle';
+} | {
+    state: 'pending';
+    proposedName: string;
+    requestId?: string;
+    retryCode?: string;
+} | {
+    state: 'approved';
+    proposedName: string;
+    approvedName?: string;
+    tokenGeneration: number;
+} | {
+    state: 'denied';
+    proposedName: string;
+} | {
+    state: 'blocked';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'unavailable';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'busy';
+};
+export interface ClaustrumEnrollmentPaths {
+    statePath: string;
+    tokenPath: string;
+}
+/** The ceremony state file sits next to the token: `x.json` pairs with `x-state.json`. */
+export declare function getClaustrumEnrollmentPaths(tokenPath: string): ClaustrumEnrollmentPaths;
+/**
+ * One host's token and state paths. Every host gets its own pair under the
+ * plugin's state directory, so an OpenCode enrollment and a Pi enrollment can
+ * be approved and revoked independently. A plugin-resolved override replaces
+ * the default token path; a relative override resolves against `cwd`.
+ */
+export declare function hostEnrollmentPaths(input: {
+    stateDir: string;
+    host: string;
+    override?: string;
+    cwd?: string;
+}): ClaustrumEnrollmentPaths;
+/** Account-file paths are injectable for isolated setup tests; no environment overrides. */
+export interface EnrollmentAncestorOptions {
+    passwdPath?: string;
+    groupPath?: string;
+}
+/**
+ * Protect setup writes from directory replacement. Group write access is safe
+ * only when local account records prove that the effective user's group is private.
+ */
+export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
+export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentStatus>;
+/** Resolve the host's account mode from its enrollment files without writing. */
+export declare function enrollmentAuthority(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<'vault' | 'local' | 'unreadable'>;
+/**
+ * Read fresh bearer material for one scoped operation; never publish it.
+ * Re-reading per operation is what lets an operator reissue a token on disk.
+ */
+export declare function readClaustrumEnrollmentToken(tokenPath: string): Promise<EnrollmentTokenFile>;
+/**
+ * The enrollment ceremony for one host. Run it from setup only: it proposes,
+ * polls and persists, and every step can wait on an operator. The request
+ * path reads the resulting token and never calls into this class.
+ */
+export declare class ClaustrumEnrollmentManager {
+    #private;
+    constructor(options: {
+        client: ClaustrumEnrollmentClient;
+        paths: ClaustrumEnrollmentPaths;
+        proposedName: string;
+        now?: () => number;
+        mintSecret?: () => string;
+        writeTokenFile?: typeof writeEnrollmentTokenFile;
+        ancestorOptions?: EnrollmentAncestorOptions;
+    });
+    status(): Promise<ClaustrumEnrollmentStatus>;
+    resetTerminal(): Promise<ClaustrumEnrollmentResetResult>;
+    reconcile(): Promise<ClaustrumEnrollmentStatus>;
+}
+export type ClaustrumEnrollmentResetResult = 'reset' | 'idle' | 'refused-pending' | 'refused-approved' | 'busy';
+/** Reset local terminal metadata without connecting to the credential daemon. */
+export declare function resetClaustrumEnrollmentState(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentResetResult>;
+export type ClaustrumEnrollmentDisconnectResult = 'disconnected' | 'idle' | 'busy';
+/**
+ * Disconnect this host from the vault on disk: remove its enrollment token,
+ * then its ceremony state, so `enrollmentAuthority` reports `local` again.
+ * This is the disconnect every plugin uses. Removing only the token is not
+ * enough: an approved state without a token is still vault mode and refuses,
+ * by design. It never contacts the credential daemon, so the enrollment stays
+ * approved in the vault until the operator revokes it there; a later Connect
+ * starts a new ceremony. A pending request is abandoned the same way.
+ *
+ * Takes the ceremony lock `reconcile()` and `resetClaustrumEnrollmentState`
+ * take, and returns `busy` without deleting anything while another process
+ * holds it. State naming another consumer refuses with `wrong-consumer` and
+ * both files stay. The token goes first: a crash between the two deletions
+ * leaves an approved state without a token, which is still vault mode (it
+ * refuses rather than falls back to local accounts), and calling this again
+ * finishes the job. Returns `idle` when neither file exists. Nothing else in
+ * the directory is touched. The token is removed without being parsed, so a
+ * corrupt token does not stand in the way. A malformed state file (bad JSON
+ * or wrong shape) is removed too, since it is what makes `enrollmentAuthority`
+ * report `unreadable`; a state file that fails the safety checks (symlink,
+ * wrong owner, not owner-only) refuses with `unsafe-file` and both files stay.
+ */
+export declare function disconnectClaustrumEnrollment(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentDisconnectResult>;