@cortexkit/common-auth 0.2.0 → 0.2.2

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 import type { StoredCredential } from './schema.js';
 /** Every library operation that can fail, as named in the failure value. */
-export type PoolOperation = 'add' | 'replace' | 'rotate' | 'disable' | 'recordIdentity' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'recordIdentity' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *

package/dist/store/index.d.ts

@@ -3,7 +3,7 @@ export type { PoolFailureKind, PoolFailurePhase, PoolOperation, } from './errors
 export { PoolOperationError, PoolReentryError } from './errors.js';
 export type { PoolLogger } from './hooks.js';
 export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
-export type { HoldPoint, WriteStep } from './mutate.js';
+export type { HoldPoint, InitializeOutcome, WriteStep } from './mutate.js';
 export type { OpenPoolStoreOptions, PoolLoad, PoolStore, } from './pool.js';
 export { openPoolStore } from './pool.js';
 export type { PullHook, PullRequest } from './pull.js';

package/dist/store/mutate.d.ts

@@ -92,6 +92,19 @@ export declare class Transaction {
     commitState(committed?: StoredCredential): Promise<void>;
     private write;
 }
+/** What `initializePool` did. */
+export type InitializeOutcome = 'initialized' | 'already-ready';
+/**
+ * Adds the pool key to a config that holds a legacy roster without one, under
+ * the store-lock list, in one config write: `commonAuthPool` with the schema
+ * version and no row entries, the legacy roster and every other top-level key
+ * kept, except the keys named in `dropKeys`. The state file is not touched.
+ * This is the only write the store makes to a pending-migration config; it is
+ * where a plugin's migration starts, and every later row goes through the
+ * ordinary operations. A config that is already a pool is left alone; a load
+ * error refuses.
+ */
+export declare function initializePool(ctx: StoreContext, dropKeys: readonly string[]): Promise<InitializeOutcome>;
 /**
  * Runs `fn` under the store-lock list. The pool must be ready: a pending
  * migration or a load error refuses before anything is written.

package/dist/store/mutate.js

@@ -195,6 +195,51 @@ export class Transaction {
         await this.ctx.onStep?.(`after-${file}-write`, this.info);
     }
 }
+/**
+ * Adds the pool key to a config that holds a legacy roster without one, under
+ * the store-lock list, in one config write: `commonAuthPool` with the schema
+ * version and no row entries, the legacy roster and every other top-level key
+ * kept, except the keys named in `dropKeys`. The state file is not touched.
+ * This is the only write the store makes to a pending-migration config; it is
+ * where a plugin's migration starts, and every later row goes through the
+ * ordinary operations. A config that is already a pool is left alone; a load
+ * error refuses.
+ */
+export async function initializePool(ctx, dropKeys) {
+    const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
+    const progress = { writes: 0 };
+    try {
+        for (const spec of ctx.storeLocks)
+            await locks.acquire(spec);
+        const result = await readPool(ctx);
+        if (result.status === 'error')
+            throw notReadyError(result, 'initialize', undefined);
+        if (result.status === 'ready')
+            return 'already-ready';
+        const next = {};
+        for (const [key, value] of Object.entries(result.config))
+            if (!dropKeys.includes(key))
+                next[key] = value;
+        next.version = LEGACY_STORE_VERSION;
+        next[POOL_KEY] = { schemaVersion: POOL_SCHEMA_VERSION, [POOL_ROWS_KEY]: {} };
+        const info = { operation: 'initialize', rowId: undefined };
+        await writeJsonAtomic(ctx.configPath, next, {
+            beforeRename: async () => {
+                await ctx.onStep?.('before-config-write', info);
+                await locks.assertAll();
+            },
+        });
+        progress.writes++;
+        await ctx.onStep?.('after-config-write', info);
+        return 'initialized';
+    }
+    catch (error) {
+        throw toFailure(error, 'initialize', undefined, progress);
+    }
+    finally {
+        await locks.releaseAll();
+    }
+}
 /**
  * Runs `fn` under the store-lock list. The pool must be ready: a pending
  * migration or a load error refuses before anything is written.

package/dist/store/pool.d.ts

@@ -1,7 +1,7 @@
 import { type Attribution } from './attribution.js';
 import type { PoolOperationError } from './errors.js';
 import type { PoolLogger } from './hooks.js';
-import { type HoldPoint, type StoreContext } from './mutate.js';
+import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mutate.js';
 import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
@@ -55,6 +55,17 @@ export interface PoolStore {
     load(): Promise<PoolLoad>;
     /** Reads the pool without firing anything. */
     read(): Promise<PoolLoad>;
+    /**
+     * Turns a pending-migration config into an empty pool (the pool key with no
+     * row entries) in one locked config write, dropping the named top-level
+     * keys and keeping the rest. The start of a plugin's migration; a ready
+     * pool is left alone. Failures carry operation `initialize`.
+     */
+    initialize(input?: {
+        dropKeys?: readonly string[];
+    }): Promise<{
+        status: InitializeOutcome;
+    }>;
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
     replace(id: string, credential: PoolCredential, input?: {
         identity?: string;

package/dist/store/pool.js

@@ -1,5 +1,5 @@
 import { recordQuota } from './attribution.js';
-import { readPool } from './mutate.js';
+import { initializePool, readPool, } from './mutate.js';
 import { PullScheduler } from './pull.js';
 import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
@@ -85,6 +85,9 @@ export function openPoolStore(options) {
         async read() {
             return toLoad(await readPool(ctx));
         },
+        async initialize(input = {}) {
+            return { status: await initializePool(ctx, input.dropKeys ?? []) };
+        },
         add: (input, callOptions) => addRow(rt, input, callOptions),
         replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
         rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),

package/dist/store/rows.d.ts

@@ -9,6 +9,13 @@ export interface RowOperationOptions {
     onFailure?: FailureHook;
     /** The provider-wide lock, when an operation may change identity keying. */
     providerLock?: PoolLockSpec;
+    /**
+     * Further locks taken after the row lock and the provider-wide lock, in
+     * this order, before the store locks: the same place `refresh` takes its
+     * extra locks, so a caller holding legacy locks around a row write and a
+     * refresh of that row acquire them in one order and cannot deadlock.
+     */
+    extraLocks?: readonly PoolLockSpec[];
 }
 export interface AddInput {
     id: string;

package/dist/store/rows.js

@@ -78,6 +78,8 @@ export async function addRow(rt, input, options = {}) {
         await locks.acquire(rowLockSpec(rt, { id, identity }));
         if (credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'add', rowId: id }, async (tx) => {
             const rows = tx.rows();
             const fingerprint = fingerprintOf(credential);
@@ -150,6 +152,8 @@ export async function replaceRow(rt, id, credential, input = {}, options = {}) {
         await locks.acquire(rowLockSpec(rt, seen));
         if (credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'replace', rowId: id }, async (tx) => {
             const row = requireUsableRow('replace', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
@@ -197,6 +201,8 @@ export async function rotateRow(rt, id, credential, input = {}, options = {}) {
         await locks.acquire(rowLockSpec(rt, seen));
         if (input.identity !== undefined && credential.type === 'oauth')
             await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(ctx, locks, progress, { operation: 'rotate', rowId: id }, async (tx) => {
             const row = requireUsableRow('rotate', id, tx.row(id), credential);
             if (rowLockKey(row) !== rowLockKey(seen))
@@ -238,6 +244,8 @@ export async function recordRowIdentity(rt, id, identity, options = {}) {
         const { row: seen } = await readRow(rt, 'recordIdentity', id);
         await locks.acquire(rowLockSpec(rt, seen));
         await locks.acquire(options.providerLock ?? rt.providerLock);
+        for (const extra of options.extraLocks ?? [])
+            await locks.acquire(extra);
         return withTransaction(rt.ctx, locks, progress, { operation: 'recordIdentity', rowId: id }, async (tx) => {
             const row = requireUsableRow('recordIdentity', id, tx.row(id));
             if (rowLockKey(row) !== rowLockKey(seen))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Shared plumbing for the CortexKit auth plugins: loopback RPC, file locks and atomic writes, logger, sidebar state file, TUI preferences and TUI build.",
   "license": "MIT",
   "repository": {