@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

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

@@ -0,0 +1,16 @@
+/**
+ * Every refusal the `/claustrum` code raises itself. Refusals sent by the
+ * vault keep arriving as the client's own `ClaustrumCredentialError` (a
+ * `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 declare class ClaustrumConsumerError extends Error {
+    readonly kind: ClaustrumConsumerFailureKind;
+    constructor(kind: ClaustrumConsumerFailureKind, message: string);
+}
+/** The structural logger every class here accepts; `/logger`'s `createLogger` satisfies it. */
+export interface ClaustrumLogger {
+    warn(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+}

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

@@ -0,0 +1,8 @@
+export class ClaustrumConsumerError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'ClaustrumConsumerError';
+        this.kind = kind;
+    }
+}

package/dist/common-auth-embedded/claustrum/host-slot.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The host's own auth slot (OpenCode's stored login for the provider, Pi's
+ * equivalent) must hold something, or the host drops the provider. Under
+ * custody it holds this placeholder: an OAuth-shaped value that is never a
+ * credential. Its empty access token also makes the vault's sealer refuse it,
+ * should it ever be offered for import.
+ */
+export declare const CUSTODY_PLACEHOLDER_PREFIX = "claustrum-tombstone:v1:";
+export declare function custodyPlaceholderKey(provider: string): string;
+export declare function custodyPlaceholder(provider: string): {
+    type: 'oauth';
+    access: '';
+    refresh: string;
+    expires: 0;
+};
+export declare function isCustodyPlaceholderValue(value: unknown): value is string;
+export declare function isCustodyPlaceholder(auth: unknown, provider: string): boolean;
+/** What the host slot holds: the custody placeholder, a real login, or nothing usable. */
+export type HostSlotContent = 'placeholder' | 'login' | 'empty';
+export declare function classifyHostSlot(auth: unknown, provider: string): HostSlotContent;
+/**
+ * Check the host slot against the plugin's mode before serving anything.
+ *
+ * - Custody mode with a real login in the slot fails closed: someone signed in
+ *   through the host while the vault owns the accounts, and serving either the
+ *   login or the vault would silently pick one. The plugin surfaces the error
+ *   and the user chooses (leave custody, or remove the login).
+ * - Local mode with the placeholder in the slot also fails: there is no local
+ *   credential to serve, and the user has to sign in.
+ *
+ * Returns the slot content when the combination is consistent.
+ */
+export declare function assertHostSlotMatchesMode(input: {
+    mode: 'custody' | 'local';
+    auth: unknown;
+    provider: string;
+}): HostSlotContent;
+/** Refuse to run a local token refresh with the placeholder as the refresh token. */
+export declare function assertNotCustodyPlaceholder(refreshToken: unknown, provider: string): void;

package/dist/common-auth-embedded/claustrum/host-slot.js

@@ -0,0 +1,72 @@
+import { ClaustrumConsumerError } from './errors.js';
+/**
+ * The host's own auth slot (OpenCode's stored login for the provider, Pi's
+ * equivalent) must hold something, or the host drops the provider. Under
+ * custody it holds this placeholder: an OAuth-shaped value that is never a
+ * credential. Its empty access token also makes the vault's sealer refuse it,
+ * should it ever be offered for import.
+ */
+export const CUSTODY_PLACEHOLDER_PREFIX = 'claustrum-tombstone:v1:';
+export function custodyPlaceholderKey(provider) {
+    return `${CUSTODY_PLACEHOLDER_PREFIX}${provider}`;
+}
+export function custodyPlaceholder(provider) {
+    return {
+        type: 'oauth',
+        access: '',
+        refresh: custodyPlaceholderKey(provider),
+        expires: 0,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isCustodyPlaceholderValue(value) {
+    return (typeof value === 'string' && value.startsWith(CUSTODY_PLACEHOLDER_PREFIX));
+}
+export function isCustodyPlaceholder(auth, provider) {
+    if (!isRecord(auth) || auth.type !== 'oauth')
+        return false;
+    return auth.refresh === custodyPlaceholderKey(provider);
+}
+export function classifyHostSlot(auth, provider) {
+    if (isCustodyPlaceholder(auth, provider))
+        return 'placeholder';
+    if (isRecord(auth) &&
+        auth.type === 'oauth' &&
+        typeof auth.refresh === 'string' &&
+        auth.refresh.length > 0 &&
+        !isCustodyPlaceholderValue(auth.refresh))
+        return 'login';
+    if (isRecord(auth) &&
+        auth.type === 'api' &&
+        typeof auth.key === 'string' &&
+        auth.key.length > 0)
+        return 'login';
+    return 'empty';
+}
+/**
+ * Check the host slot against the plugin's mode before serving anything.
+ *
+ * - Custody mode with a real login in the slot fails closed: someone signed in
+ *   through the host while the vault owns the accounts, and serving either the
+ *   login or the vault would silently pick one. The plugin surfaces the error
+ *   and the user chooses (leave custody, or remove the login).
+ * - Local mode with the placeholder in the slot also fails: there is no local
+ *   credential to serve, and the user has to sign in.
+ *
+ * Returns the slot content when the combination is consistent.
+ */
+export function assertHostSlotMatchesMode(input) {
+    const content = classifyHostSlot(input.auth, input.provider);
+    if (input.mode === 'custody' && content === 'login')
+        throw new ClaustrumConsumerError('host-slot-login', `${input.provider} has a host login while its accounts are vault-custodied; refusing to serve until one is removed`);
+    if (input.mode === 'local' && content === 'placeholder')
+        throw new ClaustrumConsumerError('host-slot-placeholder', `${input.provider} host slot holds the vault placeholder; sign in to use local accounts`);
+    return content;
+}
+/** Refuse to run a local token refresh with the placeholder as the refresh token. */
+export function assertNotCustodyPlaceholder(refreshToken, provider) {
+    if (isCustodyPlaceholderValue(refreshToken))
+        throw new ClaustrumConsumerError('placeholder-refresh', `${provider} credentials are vault-custodied; local token refresh is forbidden`);
+}

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

@@ -0,0 +1,18 @@
+import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import type { ClaustrumScopedClient } from './custody.js';
+export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
+export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
+export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
+export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+/**
+ * Connect the client that lists and fetches this consumer's vault credentials
+ * on the request path. `connectionFile` is required: this library
+ * reads no environment, so the plugin resolves the vault's connection file.
+ */
+export declare function connectClaustrumScopedClient(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): Promise<ClaustrumScopedClient>;

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

@@ -0,0 +1,22 @@
+// Claustrum vault custody shared by the auth plugins: scoped enrollment (run
+// from setup), discovery of this consumer's vault accounts as rows for this
+// package's `/routing` subpath, per-send authorization, 401 reporting, the
+// declined-account interlock and the host-slot guard. Needs the optional
+// peer `@cortexkit/claustrum-client`.
+import { ClaustrumClient, } from '@cortexkit/claustrum-client';
+export { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
+export { ClaustrumConsumer, } from './consumer.js';
+export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, SERVING_MARGIN_MS, } from './custody.js';
+export { ClaustrumEnrollmentManager, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
+export { ClaustrumConsumerError, } from './errors.js';
+export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
+export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
+/**
+ * Connect the client that lists and fetches this consumer's vault credentials
+ * on the request path. `connectionFile` is required: this library
+ * reads no environment, so the plugin resolves the vault's connection file.
+ */
+export function connectClaustrumScopedClient(options) {
+    return ClaustrumClient.connect(options);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The declined-account interlock: the user's "do not use this vault account",
+ * kept on the consumer side because the vault has no notion of it.
+ *
+ * A decline follows the provider account, not the vault record: an entry made
+ * while the account was known matches any credential id or alias that logs
+ * into that same account, so relabelling, adding an alias or removing and
+ * re-adding the account never lifts it. A credential id that now logs into a
+ * different known account does not match, because that account has its own
+ * policy. While either side's account is unknown the entry falls back to the
+ * credential id, so an adapter that makes no identity claim cannot slip past
+ * it. Never keyed on the record version, so a token refresh cannot lift it.
+ */
+export interface DeclinedAccount {
+    readonly credentialId: string;
+    readonly accountIdentity?: string;
+}
+export declare function isDeclined(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): boolean;
+export declare function declineAccount(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): DeclinedAccount[];
+/**
+ * Lift every entry that declines a row: the row's credential ids (the
+ * representative and its aliases) under the row's account. An entry for a
+ * different known account is left alone even when it names one of these
+ * credential ids, so accepting a replacement never re-enables the account the
+ * user declined.
+ */
+export declare function acceptAccount(entries: readonly DeclinedAccount[], credentialIds: readonly string[], accountIdentity?: string): DeclinedAccount[];

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

@@ -0,0 +1,29 @@
+function matches(entry, credentialId, accountIdentity) {
+    if (entry.accountIdentity !== undefined && accountIdentity !== undefined)
+        return entry.accountIdentity === accountIdentity;
+    return entry.credentialId === credentialId;
+}
+export function isDeclined(entries, credentialId, accountIdentity) {
+    return entries.some((entry) => matches(entry, credentialId, accountIdentity));
+}
+export function declineAccount(entries, credentialId, accountIdentity) {
+    const entry = {
+        credentialId,
+        ...(accountIdentity !== undefined && { accountIdentity }),
+    };
+    return [
+        ...entries.filter((existing) => existing.credentialId !== credentialId ||
+            existing.accountIdentity !== accountIdentity),
+        entry,
+    ];
+}
+/**
+ * Lift every entry that declines a row: the row's credential ids (the
+ * representative and its aliases) under the row's account. An entry for a
+ * different known account is left alone even when it names one of these
+ * credential ids, so accepting a replacement never re-enables the account the
+ * user declined.
+ */
+export function acceptAccount(entries, credentialIds, accountIdentity) {
+    return entries.filter((entry) => !credentialIds.some((id) => matches(entry, id, accountIdentity)));
+}

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

@@ -0,0 +1,208 @@
+import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import type { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
+import { type DeclinedAccount } from './interlock.js';
+/**
+ * One vault account as the pool sees it. It carries no bearer material: the
+ * access token is fetched from the vault for every send. Several vault
+ * records logged into the same provider account collapse into one row, so
+ * duplicate logins never count as extra quota.
+ */
+export interface VaultRosterRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: VaultCredentialType;
+    accountIdentity?: string;
+    /** Other credential ids logged into the same provider account. */
+    aliases?: string[];
+    state: string;
+    label: string;
+    email?: string;
+    orgName?: string;
+    enabled: boolean;
+    addedAt: number;
+    quota?: QuotaMap;
+    /**
+     * The vault listed this record in a form this consumer could not use, so the
+     * row is the last good projection kept as it was rather than dropped.
+     */
+    stale?: true;
+    /**
+     * The vault's latest list named no account for `credentialId`, so
+     * `accountIdentity` is the last account that credential was known to log
+     * into, kept until the vault names one again. It proves neither that the
+     * credential still logs into that account nor that it changed accounts.
+     */
+    unclaimed?: true;
+}
+export interface VaultRosterFile {
+    version: 1;
+    view?: string;
+    /**
+     * False when the vault's reply carried records this consumer could not use.
+     * An incomplete reply never removes an account it may still hold: every
+     * previous member it does not account for is kept.
+     */
+    complete: boolean;
+    /** The unusable records of an incomplete reply: a safe id and a fixed reason. */
+    rejected?: SkippedVaultRecord[];
+    rows: VaultRosterRow[];
+    declined: DeclinedAccount[];
+}
+/** How a vault credential is presented in the pool. */
+export type AccountMapper = (credential: VaultCredential) => {
+    label?: string;
+};
+export interface ProjectionOptions {
+    /** Ids already used by local rows; a vault route never takes one. */
+    reservedRouteIds?: ReadonlySet<string>;
+    /** Prefix for vault route ids, so they read differently from local ids. */
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    now?: number;
+}
+export declare const DEFAULT_ROUTE_PREFIX = "vault:";
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
+ */
+export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/** The ownership assertion available to a roster mutation callback. */
+export interface VaultRosterLockContext {
+    assertOwned: () => Promise<void>;
+}
+export interface MutateVaultRosterOptions {
+    /**
+     * Runs when the new roster is fully staged on disk, immediately before the
+     * rename that publishes it, so a caller can confirm a lease of its own at
+     * the moment of publication rather than when `change` returned. If it
+     * throws, nothing is published and the staged file is removed. The
+     * roster's own write lock is reasserted right after it.
+     */
+    beforePublish?: () => Promise<void>;
+}
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
+ */
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined, context: VaultRosterLockContext) => Promise<{
+    next?: VaultRosterFile;
+    result: T;
+}> | {
+    next?: VaultRosterFile;
+    result: T;
+}, options?: MutateVaultRosterOptions): Promise<T>;
+/** Mark a vault account declined; it stays listed but never routes. */
+export declare function declineVaultRoute(path: string, routeId: string): Promise<undefined>;
+/** Lift the user's decline for a vault account and every alias of it. */
+export declare function acceptVaultRoute(path: string, routeId: string): Promise<undefined>;
+/**
+ * The receipt fields a quota or profile observation must carry to say which
+ * send (credential and account) it came from. Pass the
+ * `ClaustrumScopedAttempt` that send was authorized with.
+ */
+export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accountIdentity' | 'accountIdentitySource' | 'expectedAccountIdentity'>;
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, so a slow read for a replaced account can never land on
+ * its successor. Returns whether the observation was kept.
+ */
+export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
+    routeId: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export declare function refreshVaultRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    isActive?: () => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    projection?: ProjectionOptions | (() => ProjectionOptions);
+}): Promise<VaultRosterFile | undefined>;
+/**
+ * A host-owned main account as last verified from the vault: the plugin's
+ * logical route, the credential that serves it and the account it logs into.
+ */
+export interface VaultPrimaryBinding {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    view: string;
+}
+export type VaultPrimaryUnavailableReason = 'malformed' | 'unclaimed' | 'incomplete' | 'identity-changed';
+export type VaultPrimary = 
+/**
+ * Main is bound. `replaced` is the previous binding when it named a
+ * different account: everything owned by that account (quota, profile,
+ * backoff, cache affinity) must be dropped, and outstanding observations
+ * for it fenced, even though the logical route stays the same.
+ */
+{
+    status: 'ready';
+    binding: VaultPrimaryBinding;
+    replaced?: VaultPrimaryBinding;
+}
+/** A complete reply lists no primary record: there is no main. */
+ | {
+    status: 'absent';
+}
+/**
+ * The reply cannot say who main is. Not the same as absent: the last
+ * verified binding is handed back untouched, and serving it still needs a
+ * fresh receipt that matches it.
+ */
+ | {
+    status: 'unavailable';
+    reason: VaultPrimaryUnavailableReason;
+    lastVerified?: VaultPrimaryBinding;
+};
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export declare function resolveVaultPrimary(input: {
+    inventory: VaultInventory;
+    complete?: boolean;
+    previous?: VaultPrimaryBinding;
+    expectedAccountIdentity?: string;
+    primaryCredentialId: string;
+    routeId: string;
+}): VaultPrimary;