@byokit/usage 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-10-01)
+
+
+
+- SECURITY: Claude subscription usage may read credentials only from app-managed folders under the passed stateDir, without refresh or credential writes; default logins and folder escapes are refused, tokens stay in one request and never enter output, errors, logs or stored readings.
+- Share the bounded Codex app-server client between identity and subscription usage reads.
+- Apply shared poll health, scoped quota and hard-limit semantics to managed Claude usage, including cancellable host pacing.
+
 ## 0.3.0 (2026-10-01)
 
 

package/README.md

@@ -47,6 +47,18 @@ original observation time. Poll 429 (`rate-limited`), host renewal failure
 (`refresh-failed`) and credential refusals are distinct; usage never changes
 account health or renews credentials.
 
+The managed-folder source is `{ provider: 'claude', folder, headers: { 'anthropic-beta', 'User-Agent' } }`. Paths must be absolute; removed or empty keys mean disconnected. Claude headers are app-passed. The Claude folder must resolve inside the reader's `stateDir` as `<stateDir>/claude/<hex>`, matching managed CLI account folders. Default `.claude` roots, paths outside the root, and symlinked folders or credential files are refused. Use the managed plans root as the usage reader's stateDir; its quota store coexists with the account roster. The default login's usage adapter remains with the host.
+
+Approved exception: the `./cli` entry reads and runs only app-managed per-account folders under `stateDir` and the absolute CLI binaries the app passes; it never touches the person's default login; tokens never leave the device and are never logged. Under the same managed-folder boundary, usage may read `.credentials.json` only for a single Claude subscription usage request. It does not refresh, write, rename or copy credentials; expired or malformed credentials return `expired` or `not-connected`, requiring sign-in again. The token is held in memory only for that request and never enters readings, stored quotas, errors or logs. Folder and credential metadata supply the cache fingerprint without loading a token, and credential changes invalidate the cached account reading.
+
+`read(source, { nowMs? })` returns `{ provider, windows, at, code? }`; `at` and all
+`resetsAt` fields are **epoch milliseconds** in 0.2.0. This changes 0.1.0's seconds
+reset convention. Windows include kind, used percent, optional duration in minutes,
+reset time, limit label and limited flag. Parsers are exported for host integrations:
+`claudeWindows`, `codexWindows` (app-server), `codexTokenWindows`, `goWindows`,
+`zaiWindows`, `copilotWindows`, `grokWindows`, `minimaxWindows`, `geminiWindows`,
+`kimiWindows(raw, nowMs)`.
+
 Windows include kind, optional reported `usedPercent`, duration, reset, limit,
 `limited` and `scope: { model?, surface? }`. Missing usage is unknown, never zero.
 Claude `limits[]` session/weekly-all rows override corresponding legacy aggregates,
@@ -197,6 +209,8 @@ and HOME explicitly when needed. No tokens in logs, errors, readings or public h
 no credential write-back, telemetry, automatic refresh or reset-credit spend.
 
 Built-in requests send `User-Agent: byokit/usage/0.3.0`, never another app's identity.
+
+Token and explicit-file sources send `User-Agent: byokit/usage/0.2.0`, never another app's identity.
 A refusal returns a code; with no last-good quota, room is unknown. Fixed endpoints
 are Anthropic `api/oauth/usage`, ChatGPT `backend-api/wham/usage`, GitHub
 `copilot_internal/user`, Grok `v1/billing` (weekly credits then monthly when needed),
@@ -269,3 +283,7 @@ When passing normalized windows to `@byokit/accounts`' structural helper, use
 legacy reset seconds; normalized usage windows in 0.2.0+ already use milliseconds.
 Alternatively, this package's `roomOf(reading, nowMs)` returns a structural `Room`
 that the accounts chooser accepts directly. Preserve the original measurement time.
+
+`identity(codexSource)` shares the app-server transport, calls `account/read` with a 15-second deadline, never opens a credential file, and returns only `{signedIn,email?,plan?}`. Managed-folder HTTP usage carries only the app-passed headers plus Bearer authorization and JSON accept; it uses the same bounded HTTP transport.
+
+Managed-folder Claude usage uses the shared poll-health and normalized quota pipeline, including scoped hard blocks, unknown usage, last-good observation times, account retry policies and cancellable host origin pacing.

package/dist/claude.d.ts

@@ -0,0 +1,12 @@
+import { providerHttp, type Answer } from './providers.ts';
+import type { Source } from './types.ts';
+type ClaudeSource = Extract<Source, {
+    folder: string;
+}>;
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export declare function managedClaudeFolder(folder: string, stateDir: string): boolean;
+/** Metadata only, so account/cache probes never load a token. */
+export declare function claudeCredential(folder: string): import("fs").Stats | undefined;
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export declare function claudeUsage(source: ClaudeSource, fetcher: typeof fetch, nowMs: number, pacing?: Parameters<typeof providerHttp>[5]): Promise<Answer>;
+export {};

package/dist/claude.js

@@ -0,0 +1,47 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { readJson } from "./store.js";
+import { record } from "./windows.js";
+import { providerHttp } from "./providers.js";
+/** No ambient HOME discovery. Both the lexical and real folder must be managed by this root. */
+export function managedClaudeFolder(folder, stateDir) {
+    const root = resolve(stateDir);
+    const candidate = resolve(folder);
+    if (root.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+        return false;
+    const parent = join(root, 'claude');
+    if (!candidate.startsWith(parent + sep) || !/^[a-f0-9]+$/.test(candidate.slice(parent.length + 1)))
+        return false;
+    try {
+        if (![root, parent, candidate].every((path) => { const s = lstatSync(path); return s.isDirectory() && !s.isSymbolicLink(); }))
+            return false;
+        const realRoot = realpathSync(root);
+        if (realRoot.split(sep).some((part) => ['.claude', '.codex', '.pi'].includes(part)))
+            return false;
+        const realFolder = realpathSync(candidate);
+        return realFolder.startsWith(join(realRoot, 'claude') + sep);
+    }
+    catch {
+        return false;
+    }
+}
+/** Metadata only, so account/cache probes never load a token. */
+export function claudeCredential(folder) {
+    try {
+        const stat = lstatSync(join(folder, '.credentials.json'));
+        return stat.isFile() && !stat.isSymbolicLink() && stat.size <= 64 * 1024 ? stat : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The credential is held only for this request; no refresh, writes or recovery sidecars. */
+export async function claudeUsage(source, fetcher, nowMs, pacing) {
+    const raw = readJson(join(source.folder, '.credentials.json'), 64 * 1024);
+    const oauth = record(raw) && record(raw.claudeAiOauth) ? raw.claudeAiOauth : undefined;
+    if (!oauth || typeof oauth.accessToken !== 'string' || !oauth.accessToken.trim() || oauth.accessToken.length > 16384 || /[\x00-\x20\x7f]/.test(oauth.accessToken))
+        return { code: 'not-connected' };
+    if (typeof oauth.expiresAt !== 'number' || !Number.isFinite(oauth.expiresAt) || oauth.expiresAt <= nowMs)
+        return { code: 'expired' };
+    return providerHttp('https://api.anthropic.com/api/oauth/usage', oauth.accessToken, fetcher, nowMs, { headers: { 'anthropic-beta': source.headers['anthropic-beta'], 'User-Agent': source.headers['User-Agent'] } }, pacing);
+}

package/dist/identity.d.ts

@@ -0,0 +1,11 @@
+import type { Source } from './types.ts';
+export type Identity = {
+    signedIn: boolean;
+    email?: string;
+    plan?: string;
+};
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export declare function publicIdentity(raw: unknown, signedIn: boolean): Identity;
+export declare function codexIdentity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;

package/dist/identity.js

@@ -0,0 +1,16 @@
+import { codexRequest } from "./providers.js";
+import { record } from "./windows.js";
+/** Explicit identity fields only: never walk arbitrary token-bearing objects. */
+export function publicIdentity(raw, signedIn) {
+    if (!signedIn || !record(raw))
+        return { signedIn: false };
+    const short = (value) => typeof value === 'string' && value.length > 0 && value.length <= 320 && !/[\x00-\x1f\x7f]/.test(value);
+    const email = short(raw.email) && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.email) ? raw.email : undefined;
+    const plan = [raw.planType, raw.subscriptionType, raw.plan, raw.tier, raw.planName].find((value) => short(value) && /^[a-zA-Z][a-zA-Z0-9 _+-]{0,63}$/.test(value));
+    return { signedIn: true, ...(email === undefined ? {} : { email }), ...(typeof plan === 'string' ? { plan } : {}) };
+}
+export async function codexIdentity(source) {
+    const answer = await codexRequest(source, 'account/read');
+    const account = record(answer.raw) ? answer.raw.account : undefined;
+    return publicIdentity(account, record(account));
+}

package/dist/index.d.ts

@@ -1,5 +1,11 @@
-import { type Usage, type UsageOptions } from './types.ts';
+import { type Source, type Usage, type UsageOptions } from './types.ts';
+import { type Identity } from './identity.ts';
 export * from './types.ts';
+export type { Identity } from './identity.ts';
+/** Identity runs only the named binary, never opens a credential file. */
+export declare function identity(source: Extract<Source, {
+    bin: string;
+}>): Promise<Identity>;
 export { callLedger, normalizeTokens, priceCall, type CallLedger, type CallInput, type CallRecord, type CallQuery, type NormalizedTokens, type ModelPrice, type PriceTable, type CallCost } from './calls.ts';
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError, type TokenLedger, type TokenLedgerStore, type TokenLedgerOptions, type TokenEntry, type TokenQuery } from './ledger.ts';
 export { roomOf } from './room.ts';

package/dist/index.js

@@ -6,7 +6,16 @@ import { fingerprint, readJson, store, memoryUsageStore, safeWindows, safePoll }
 import { claudeWindows, codexWindows, goWindows, record, zaiWindows } from "./windows.js";
 import { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimaxWindows, geminiWindows, kimiWindows } from "./quota.js";
 import { UsageError } from "./types.js";
+import { codexIdentity } from "./identity.js";
+import { claudeUsage as managedClaudeUsage, claudeCredential, managedClaudeFolder } from "./claude.js";
 export * from "./types.js";
+/** Identity runs only the named binary, never opens a credential file. */
+export async function identity(source) {
+    if (!record(source) || !('bin' in source) || 'folder' in source || 'credentialsFile' in source || 'read' in source)
+        throw new UsageError();
+    validate(source);
+    return codexIdentity(source);
+}
 export { callLedger, normalizeTokens, priceCall } from "./calls.js";
 export { tokenLedger, memoryTokenLedgerStore, TokenLedgerError } from "./ledger.js";
 export { roomOf } from "./room.js";
@@ -17,10 +26,16 @@ export { codexHardLimit, codexTokenWindows, copilotWindows, grokWindows, minimax
 export { WORDS, words, usageWords } from "./words.js";
 const providers = ['claude', 'codex', 'opencode', 'zai', 'copilot', 'grok', 'minimax', 'gemini', 'kimi'];
 const validText = (v) => typeof v === 'string' && !v.includes('\0') && !/[\r\n]/.test(v) && v.length <= 16384;
-function validate(source) {
+function validate(source, stateDir) {
     if (!record(source) || !providers.includes(source.provider))
         throw new UsageError();
-    if ('credentialsFile' in source) {
+    if ('folder' in source) {
+        if (source.provider !== 'claude' || !validText(source.folder) || !isAbsolute(source.folder) || !stateDir || !managedClaudeFolder(source.folder, stateDir))
+            throw new UsageError();
+        if (!record(source.headers) || !['anthropic-beta', 'User-Agent'].every((key) => validText(source.headers[key]) && source.headers[key].length <= 1024))
+            throw new UsageError();
+    }
+    else if ('credentialsFile' in source) {
         if (source.provider !== 'claude' || ![source.credentialsFile, ...[source.configFile, source.statuslineFile].filter((v) => v !== undefined)].every((v) => validText(v) && isAbsolute(v)))
             throw new UsageError();
     }
@@ -84,7 +99,9 @@ export function usage(options) {
     const failures = new Map();
     const now = (opts) => opts?.nowMs ?? (options.now ?? Date.now)();
     function connected(source) {
-        validate(source);
+        validate(source, options.stateDir);
+        if ('folder' in source)
+            return claudeCredential(source.folder) !== undefined;
         if ('credentialsFile' in source)
             return claudeAuth(source) !== undefined;
         if ('read' in source) {
@@ -107,9 +124,13 @@ export function usage(options) {
         return ('access' in source ? source.access : source.key).trim() !== '';
     }
     function account(source) {
-        validate(source);
+        validate(source, options.stateDir);
         let id;
-        if ('credentialsFile' in source)
+        if ('folder' in source) {
+            const stat = claudeCredential(source.folder);
+            id = stat ? `${source.folder}\0${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : undefined;
+        }
+        else if ('credentialsFile' in source)
             id = claudeAuth(source)?.account;
         else if ('read' in source)
             id = source.accountUuid;
@@ -164,7 +185,7 @@ export function usage(options) {
         }
     }
     async function read(source, opts) {
-        validate(source);
+        validate(source, options.stateDir);
         const clock = now(opts);
         const empty = (code) => ({ provider: source.provider, windows: [], code, poll: { at: clock, outcome: code ?? 'unavailable' } });
         if (!connected(source))
@@ -202,7 +223,7 @@ export function usage(options) {
             let answer;
             const pacing = { hook: options.pace, provider: source.provider, account: id.key, signal: opts?.signal };
             try {
-                answer = 'read' in source ? await customClaude(source, clock, pacing) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing)
+                answer = 'folder' in source ? await managedClaudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing) : 'read' in source ? await customClaude(source, clock, pacing) : 'credentialsFile' in source ? await claudeUsage(source, options.fetch ?? globalThis.fetch, clock, pacing)
                     : 'bin' in source ? await codexUsage(source) : await providerGet(source, options.fetch ?? globalThis.fetch, clock, pacing);
             }
             catch {

package/dist/providers.d.ts

@@ -5,6 +5,16 @@ type TokenSource = Extract<Source, {
 } | {
     key: string;
 }>;
+/** One bounded request; credentials and response bodies never become errors. */
+export declare function providerHttp(url: string, key: string, fetcher: typeof fetch, nowMs: number, extra?: {
+    headers?: Record<string, string>;
+    body?: unknown;
+}, pacing?: {
+    hook?: PacingHook;
+    provider: Source['provider'];
+    account: string;
+    signal?: AbortSignal;
+}): Promise<Answer>;
 export declare function providerGet(source: TokenSource, fetcher: typeof fetch, nowMs: number, pacing?: {
     hook?: PacingHook;
     provider: Source['provider'];
@@ -22,6 +32,10 @@ export declare function customClaude(source: Extract<Source, {
 export declare function codexUsage(source: Extract<Source, {
     bin: string;
 }>): Promise<Answer>;
+/** The single bounded app-server transport used for identity and usage. */
+export declare function codexRequest(source: Extract<Source, {
+    bin: string;
+}>, method: 'account/read' | 'account/rateLimits/read', timeoutMs?: number): Promise<Answer>;
 /** Re-read the tool's credentials so its own renewal is picked up; never renew or write them. */
 export declare function claudeAuth(source: Extract<Source, {
     credentialsFile: string;

package/dist/providers.js

@@ -5,7 +5,7 @@ import { claudeWindows, record } from "./windows.js";
 import { grokWindows } from "./quota.js";
 const USER_AGENT = 'byokit/usage/0.2.0';
 /** One bounded request; credentials and response bodies never become errors. */
-async function request(url, key, fetcher, nowMs, extra = {}, pacing) {
+export async function providerHttp(url, key, fetcher, nowMs, extra = {}, pacing) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     pacing?.signal?.addEventListener('abort', abort, { once: true });
@@ -69,7 +69,7 @@ async function request(url, key, fetcher, nowMs, extra = {}, pacing) {
 }
 export async function providerGet(source, fetcher, nowMs, pacing) {
     const key = 'access' in source ? source.access : source.key;
-    const get = (url, extra) => request(url, key, fetcher, nowMs, extra, pacing);
+    const get = (url, extra) => providerHttp(url, key, fetcher, nowMs, extra, pacing);
     switch (source.provider) {
         case 'claude': return get('https://api.anthropic.com/api/oauth/usage', { headers: { 'anthropic-beta': 'oauth-2025-04-20' } });
         case 'codex': return get('https://chatgpt.com/backend-api/wham/usage', { headers: { 'ChatGPT-Account-Id': source.accountId } });
@@ -138,6 +138,10 @@ export async function customClaude(source, nowMs, pacing) {
     }
 }
 export function codexUsage(source) {
+    return codexRequest(source, 'account/rateLimits/read', 20_000);
+}
+/** The single bounded app-server transport used for identity and usage. */
+export function codexRequest(source, method, timeoutMs = 15_000) {
     return new Promise((resolve) => {
         const child = spawn(source.bin, ['app-server'], { env: { ...source.env, CODEX_HOME: source.home }, stdio: ['pipe', 'pipe', 'ignore'] });
         let buffer = '';
@@ -156,7 +160,7 @@ export function codexUsage(source) {
             }
             resolve(answer);
         };
-        const timer = setTimeout(() => finish({ code: 'unavailable' }), 20_000);
+        const timer = setTimeout(() => finish({ code: 'unavailable' }), timeoutMs);
         child.once('error', () => finish({ code: 'unavailable' }));
         child.once('close', () => { clearTimeout(escalation); finish({ code: 'unavailable' }); });
         child.stdin.on('error', () => finish({ code: 'unavailable' }));
@@ -181,7 +185,7 @@ export function codexUsage(source) {
                     if (!record(message))
                         continue;
                     if (message.id === 1)
-                        child.stdin.write(`${JSON.stringify({ id: 2, method: 'account/rateLimits/read', params: {} })}\n`);
+                        child.stdin.write(`${JSON.stringify({ id: 2, method, params: {} })}\n`);
                     if (message.id === 2)
                         finish(record(message.result) ? { raw: message.result } : { code: 'incomplete' });
                 }

package/dist/types.d.ts

@@ -4,6 +4,13 @@ type Identity = {
     accountId?: string;
 };
 export type Source = {
+    provider: 'claude';
+    folder: string;
+    headers: {
+        'anthropic-beta': string;
+        'User-Agent': string;
+    };
+} | {
     provider: 'codex';
     bin: string;
     home: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/usage",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Read subscription usage windows per provider and account.",
   "license": "Apache-2.0",
   "type": "module",