@permute/sdk 0.8.0 → 0.8.1

package/README.md

@@ -20,6 +20,10 @@ bunx @permute/sdk auth logout
 
 Choose an organization, optionally limit the connection to one workspace, then select resources and permissions to approve in Permute. The CLI stores renewable credentials in your operating system’s credential store (no plaintext fallback). Active logins have no fixed maximum lifetime and expire after 30 days without renewal; company sign-in rules can require earlier authentication. Logging out revokes access before removing the local credential. Signing in again revokes the previous stored CLI session.
 
+The SDK reuses credentials in memory between requests and reloads the OS store before renewal or when another process changes the saved login. The local auth directory holds only a lock and a non-secret change marker; tokens stay out of ordinary files. Current server permissions and revocation still apply to every request.
+
+The CLI prints the issuer and `permute-cli` entry name to stderr before accessing the OS store. macOS controls its own permission dialog, which may identify the Node or Bun process. SDK applications stay silent by default and can supply `onCredentialStoreAccess: (issuer) => { /* show a notice */ }` to `OAuthLogin`; the callback runs once before the default OS store is accessed and receives no credentials.
+
 ```ts
 import { OAuthLogin } from '@permute/sdk/auth';
 

package/dist/auth/oauth.d.ts

@@ -8,6 +8,8 @@ export interface OAuthOptions {
     apiUrl?: string;
     store?: CredentialStore;
     fetch?: typeof fetch;
+    /** Called once before the default OS credential store is accessed; no tokens are passed. */
+    onCredentialStoreAccess?: (issuer: string) => void;
 }
 export declare class OAuthLogin {
     readonly issuer: string;

package/dist/auth/oauth.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { createHash, randomBytes } from 'node:crypto';
 import { setTimeout } from 'node:timers/promises';
 import { PermuteClient } from '../client.js';
-import { SystemCredentialStore } from './store.js';
+import { TOKEN_REFRESH_BUFFER_MS, SystemCredentialStore, } from './store.js';
 export { SystemCredentialStore } from './store.js';
 export const DEFAULT_ISSUER = 'https://auth.permute.ai';
 const CLIENT_ID = 'permute-cli';
@@ -30,7 +30,7 @@ export class OAuthLogin {
     constructor(options = {}) {
         this.issuer = this.endpoint(options.issuer ?? DEFAULT_ISSUER);
         this.apiUrl = this.endpoint(options.apiUrl ?? 'https://api.permute.ai');
-        this.store = options.store ?? new SystemCredentialStore(this.issuer);
+        this.store = options.store ?? new SystemCredentialStore(this.issuer, options.onCredentialStoreAccess);
         this.fetchImpl = options.fetch ?? fetch;
     }
     endpoint(value) {
@@ -65,7 +65,7 @@ export class OAuthLogin {
             throw new Error('Invalid credential response');
         return parsed.data;
     }
-    async persist(tokens) {
+    async persist(tokens, previous) {
         const credentials = {
             issuer: this.issuer,
             apiUrl: this.apiUrl,
@@ -77,9 +77,9 @@ export class OAuthLogin {
             expiresAt: Date.now() + tokens.expires_in * 1000,
         };
         try {
-            const previous = await this.store.read();
-            if (previous && previous.sessionId !== tokens.session_id)
-                await this.revoke(previous.refresh);
+            const existing = previous ?? (await this.store.read());
+            if (existing && existing.sessionId !== tokens.session_id)
+                await this.revoke(existing.refresh);
             await this.store.write(credentials);
         }
         catch (error) {
@@ -172,14 +172,14 @@ export class OAuthLogin {
             const current = await this.store.read();
             if (!current || current.apiUrl !== this.apiUrl)
                 throw new Error('No login for this server. Run permute auth login.');
-            if (current.expiresAt > Date.now() + 60_000)
+            if (current.expiresAt > Date.now() + TOKEN_REFRESH_BUFFER_MS)
                 return current;
             const tokens = this.tokens(await this.post('/token', {
                 client_id: CLIENT_ID,
                 grant_type: 'refresh_token',
                 refresh_token: current.refresh,
             }));
-            return this.persist(tokens);
+            return this.persist(tokens, current);
         });
     }
     async client() {

package/dist/auth/store.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare const TOKEN_REFRESH_BUFFER_MS = 60000;
 declare const LoginCredentialsSchema: z.ZodObject<{
     issuer: z.ZodString;
     apiUrl: z.ZodString;
@@ -16,11 +17,16 @@ export interface CredentialStore {
     remove(): Promise<void>;
     exclusive<T>(run: () => Promise<T>): Promise<T>;
 }
-/** Tokens never fall back to a plaintext file. The disk lock contains no credentials. */
+/** Credentials are cached in memory only; disk holds a lock and a non-secret change marker. */
 export declare class SystemCredentialStore implements CredentialStore {
     private readonly issuer;
+    private readonly onAccess?;
     private readonly account;
-    constructor(issuer: string);
+    private readonly directory;
+    private readonly revisionPath;
+    private cached?;
+    private announced;
+    constructor(issuer: string, onAccess?: ((issuer: string) => void) | undefined);
     private entry;
     read(): Promise<{
         issuer: string;
@@ -32,8 +38,10 @@ export declare class SystemCredentialStore implements CredentialStore {
         refresh: string;
         expiresAt: number;
     } | null>;
+    private validate;
     write(value: LoginCredentials): Promise<void>;
     remove(): Promise<void>;
+    private markChanged;
     exclusive<T>(run: () => Promise<T>): Promise<T>;
 }
 export {};

package/dist/auth/store.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { mkdir, rm } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { setTimeout } from 'node:timers/promises';
+export const TOKEN_REFRESH_BUFFER_MS = 60_000;
 const LoginCredentialsSchema = z.object({
     issuer: z.string().url(),
     apiUrl: z.string().url(),
@@ -14,39 +15,74 @@ const LoginCredentialsSchema = z.object({
     refresh: z.string().min(1),
     expiresAt: z.number().finite(),
 });
-/** Tokens never fall back to a plaintext file. The disk lock contains no credentials. */
+/** Credentials are cached in memory only; disk holds a lock and a non-secret change marker. */
 export class SystemCredentialStore {
     issuer;
+    onAccess;
     account;
-    constructor(issuer) {
+    directory = join(homedir(), '.config', 'permute', 'auth');
+    revisionPath;
+    cached;
+    announced = false;
+    constructor(issuer, onAccess) {
         this.issuer = issuer;
+        this.onAccess = onAccess;
         this.account = createHash('sha256').update(issuer).digest('hex');
+        this.revisionPath = join(this.directory, `${this.account}.revision`);
     }
     async entry() {
         const { AsyncEntry } = await import('@napi-rs/keyring');
+        if (!this.announced) {
+            this.onAccess?.(this.issuer);
+            this.announced = true;
+        }
         return new AsyncEntry('permute-cli', this.account, { linux: { store: 'secret-service' } });
     }
     async read() {
+        const revision = await readFile(this.revisionPath, 'utf8').catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (this.cached?.revision === revision && this.cached.value.expiresAt > Date.now() + TOKEN_REFRESH_BUFFER_MS)
+            return { ...this.cached.value };
+        this.cached = undefined;
         const value = await (await this.entry()).getPassword();
         if (!value)
             return null;
-        const parsed = LoginCredentialsSchema.safeParse(JSON.parse(value));
+        const credentials = this.validate(JSON.parse(value));
+        this.cached = { revision, value: credentials };
+        return { ...credentials };
+    }
+    validate(value) {
+        const parsed = LoginCredentialsSchema.safeParse(value);
         if (!parsed.success || parsed.data.issuer !== this.issuer)
             throw new Error('Stored login is invalid. Run permute auth login again.');
         return parsed.data;
     }
     async write(value) {
-        await (await this.entry()).setPassword(JSON.stringify(value));
+        const credentials = this.validate(value);
+        this.cached = undefined;
+        await (await this.entry()).setPassword(JSON.stringify(credentials));
+        const revision = await this.markChanged();
+        this.cached = { revision, value: credentials };
     }
     async remove() {
+        this.cached = undefined;
         const entry = await this.entry();
         if (await entry.getPassword())
             await entry.deletePassword();
+        await this.markChanged();
+    }
+    async markChanged() {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const revision = randomUUID();
+        await writeFile(this.revisionPath, revision, { mode: 0o600 });
+        return revision;
     }
     async exclusive(run) {
-        const directory = join(homedir(), '.config', 'permute', 'auth');
-        await mkdir(directory, { recursive: true, mode: 0o700 });
-        const lock = join(directory, `${this.account}.lock`);
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const lock = join(this.directory, `${this.account}.lock`);
         const deadline = Date.now() + 30_000;
         while (true) {
             const acquired = await mkdir(lock, { mode: 0o700 }).then(() => true, (error) => {

package/dist/cli.js

@@ -90,7 +90,14 @@ export async function runCli(args = process.argv.slice(2)) {
     }
     if (!!values.issuer !== !!values['api-url'])
         throw new Error('Provide both --issuer and --api-url for another environment.');
-    const login = new OAuthLogin({ issuer: values.issuer, apiUrl: values['api-url'] });
+    const login = new OAuthLogin({
+        issuer: values.issuer,
+        apiUrl: values['api-url'],
+        onCredentialStoreAccess: (issuer) => {
+            const store = process.platform === 'darwin' ? 'macOS Keychain' : 'your OS credential store';
+            console.error(`Permute CLI is accessing ${store} for ${issuer} (entry: permute-cli).`);
+        },
+    });
     if (command === 'logout') {
         await login.logout();
         console.log('CLI login revoked and removed from this device.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@permute/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "TypeScript client for the Permute public API",
   "type": "module",
   "license": "Apache-2.0",