@wirecat/cli-core 0.565.0 → 0.566.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ shape of this file.
 
 ## Unreleased
 
+## 0.566.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **cli-core now needs `@wirecat/cli-base` 0.76.0 or later** (peer range `>=0.76.0 <0.78.0`), which holds
+  `loadConstants`.
+- **`appDoctorCommand`'s `oauthClient` returns `oauthClientReport`'s shape, `{ client, source, reason? }`**, and a
+  throw there is reported as `{ client: null, source: null, reason }` (was `error`). drive's and gcal's callers
+  change with their bump.
+
+### Added
+
+- **`@wirecat/cli-core/constants`: WireCat's sign-in apps ship in cli-core's `constants.json`.** `constants()` reads
+  cli-base's, cli-core's and the tool's `constants.json` once per process, merged, validated and frozen; a tool
+  passes its own layer and a schema built on `constantsSchema`. It holds WireCat's Google Desktop app
+  (`google.app.client_id`, `client_secret`) and Microsoft client id (`microsoft.app.client_id`), which drive and mail
+  kept in source and gcal expected from a file CI wrote. `googleApp({ env, prefix, clientFile, clientId,
+  configClientId })` and `microsoftApp(…)` pick the app in WC-SECR-25's order: `--client-file` or `--client-id`
+  (`flag`), `<PREFIX>_<PROVIDER>_CLIENT_ID` (`env`), the account's `<provider>.client_id` (`config`), WireCat's app
+  (`constants`); a `_SECRET` with no id is a `configuration_error`, reason `sign-in.secret-without-id`. `oauthApp`
+  does the same for a provider whose app is in a tool's layer, such as Zoom, and returns nothing when there is none.
+  `oauthClientReport(app, reason?)` is `doctor`'s `oauth_client`: `{ client: "wirecat" | "own" | null, source }`.
+  See [Constants](docs/dev/CONSTANTS.md).
+- **A sign-in entry records where its app came from** (`clientSource` in the standard and drive entries, read back
+  as `client.source`), so `doctor` reports the app the account signed in with. The standard entry also keeps
+  WireCat's public secret, so a refresh still works after a release ships another default app; an owner's own
+  secret is still never written.
+
 ## 0.565.0 — 05.11.2026
 
 ### Changed — may break callers

package/constants.json

@@ -0,0 +1,13 @@
+{
+  "google": {
+    "app": {
+      "client_id": "_WAlQe_1Jamd97lrbGU1kcXOJ8TWiJSbdfyTOEEF6IqtlI9-L2lr8iTW7MmAqUn7XMpK1OXeRZNLCFlYULdV3C5HGV28xT2CL0QFEI3FC3oHZp-ak5TX9g",
+      "client_secret": "X6afcHNZ_v0d_N6-jCWHFQSeT2O-saKLY8_WY_W5aIlswI6q2EZ6GtF3IFhy6WjIHUzB"
+    }
+  },
+  "microsoft": {
+    "app": {
+      "client_id": "f7f05d3a-b948-4d50-b3ce-59c816ce69e9"
+    }
+  }
+}

package/dist/cli/app-doctor-command.d.ts

@@ -1,14 +1,14 @@
 import { Command } from "commander";
+import type { OAuthClientReport } from "../constants/index.js";
 import { type AppIdentity } from "../ports/app.js";
 import type { Configuration } from "./settings.js";
 export interface AppDoctorOptions {
     /**
-     * Which OAuth client the CLI signs in with — WireCat's or one of the owner's own — read from the environment and
-     * files only. A throw is reported as its message.
+     * The OAuth app a new sign-in would use (WC-SECR-25), read from the environment and files only, usually
+     * `oauthClientReport` of the tool's `googleApp`/`oauthApp`. A throw is reported as a null client with its message as
+     * the reason.
      */
-    oauthClient?: (env: NodeJS.ProcessEnv) => {
-        client: "wirecat" | "own";
-    };
+    oauthClient?: (env: NodeJS.ProcessEnv) => OAuthClientReport;
     /** The npm package, so `--online` can say whether a newer version is published; without it that check is left out. */
     packageName?: string;
     /**
@@ -48,10 +48,7 @@ export declare const appDoctorReport: (app: AppIdentity, configuration: Configur
             path: string;
             exists: boolean;
         };
-        oauth_client?: {
-            client: "wirecat" | "own" | null;
-            error?: string;
-        } | undefined;
+        oauth_client?: OAuthClientReport | undefined;
         read_only: string | null;
         profile_lock: string | null;
         config: {
@@ -90,10 +87,7 @@ export declare const appDoctorReport: (app: AppIdentity, configuration: Configur
             path: string;
             exists: boolean;
         };
-        oauth_client?: {
-            client: "wirecat" | "own" | null;
-            error?: string;
-        } | undefined;
+        oauth_client?: OAuthClientReport | undefined;
         read_only: string | null;
         profile_lock: string | null;
         config: {

package/dist/cli/app-doctor-command.js

@@ -85,7 +85,7 @@ export const appDoctorReport = (app, configuration, env, command, options = {})
             oauth = options.oauthClient(env);
         }
         catch (error) {
-            oauth = { client: null, error: failure(error) };
+            oauth = { client: null, source: null, reason: failure(error) };
         }
     const common = {
         version: app.version,

package/dist/constants/index.d.ts

@@ -0,0 +1,83 @@
+import * as v from "valibot";
+import type { AppSource, OAuthClient } from "../oauth/provider.js";
+/** cli-core's layer, read after cli-base's and before the tool's. */
+export declare const CORE_CONSTANTS: import("url").URL;
+/** What cli-base's and cli-core's layers hold; a tool extends it with `v.object({ ...constantsSchema.entries, … })`. */
+export declare const constantsSchema: v.ObjectSchema<{
+    readonly google: v.ObjectSchema<{
+        readonly app: v.ObjectSchema<{
+            readonly client_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.TransformAction<string, string>]>;
+            readonly client_secret: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, string>]>, undefined>;
+        }, undefined>;
+    }, undefined>;
+    readonly microsoft: v.ObjectSchema<{
+        readonly app: v.ObjectSchema<{
+            readonly client_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>]>;
+        }, undefined>;
+    }, undefined>;
+}, undefined>;
+export type Constants = v.InferOutput<typeof constantsSchema>;
+/**
+ * The packaged constants, base → core → the tool's `constants.json` when given, read once per process for each tool
+ * layer. A tool with constants of its own passes its layer and a schema built on `constantsSchema`; the first call for
+ * a layer decides its schema.
+ */
+export declare const constants: <TSchema extends v.GenericSchema<unknown, Constants> = typeof constantsSchema>(toolLayer?: URL, schema?: TSchema) => v.InferOutput<TSchema>;
+export interface AppOptions {
+    env: NodeJS.ProcessEnv;
+    /** The tool's environment prefix: `GCAL` with provider `google` reads `GCAL_GOOGLE_CLIENT_ID` and `_SECRET`. */
+    prefix: string;
+    /** `--client-id`. A secret for it comes from `<PREFIX>_<PROVIDER>_CLIENT_SECRET`. */
+    clientId?: string | undefined;
+    /** The account's config key `<provider>.client_id`. A config file never holds the secret: it comes from the env. */
+    configClientId?: string | undefined;
+}
+export interface OAuthAppOptions extends AppOptions {
+    /** `google`, `microsoft`, `zoom`: names the env variables, upper-cased. */
+    provider: string;
+    /** WireCat's app from the constants; an empty or missing id means WireCat has none for this provider. */
+    wirecat?: {
+        client_id?: string | undefined;
+        client_secret?: string | undefined;
+    } | undefined;
+}
+export interface OAuthApp {
+    client: OAuthClient & {
+        source: AppSource;
+    };
+    source: AppSource;
+}
+/**
+ * The app a sign-in uses, first match wins (WC-SECR-25): `--client-id`, `<PREFIX>_<PROVIDER>_CLIENT_ID`, the account's
+ * `<provider>.client_id`, WireCat's app. A secret without any of the first three ids is a `configuration_error`.
+ * Undefined when nothing names an app and WireCat has none.
+ */
+export declare const oauthApp: (options: OAuthAppOptions) => OAuthApp | undefined;
+export interface GoogleAppOptions extends AppOptions {
+    /** The owner's Desktop client JSON, `--client-file`; it must be private to the owner. */
+    clientFile?: string | undefined;
+    platform?: NodeJS.Platform;
+    /** The tool's own constants, when its layer overrides the app. */
+    constants?: Constants;
+}
+/**
+ * The Google Desktop app a sign-in uses: `--client-file`, then `oauthApp`'s order. Google treats a Desktop app's
+ * secret as public (https://developers.google.com/identity/protocols/oauth2/native-app), so WireCat's ships, obscured,
+ * in cli-core's constants.
+ */
+export declare const googleApp: (options: GoogleAppOptions) => OAuthApp;
+/** WireCat's Microsoft app is a public client: it has an id and no secret. */
+export declare const microsoftApp: (options: AppOptions & {
+    constants?: Constants;
+}) => OAuthApp;
+export interface OAuthClientReport {
+    client: "wirecat" | "own" | null;
+    source: AppSource | null;
+    /** Why there is no app, when `client` is null. */
+    reason?: string;
+}
+/** `doctor`'s `oauth_client` for one provider: the app a new sign-in would use; doctor reads no keyring. */
+export declare const oauthClientReport: (app: {
+    source?: AppSource | undefined;
+} | undefined, reason?: string) => OAuthClientReport;
+export type { AppSource };

package/dist/constants/index.js

@@ -0,0 +1,77 @@
+import { BASE_CONSTANTS, baseConstantsSchema, CliError, loadConstants } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { readClientFile } from "../oauth/client-file.js";
+import { reveal } from "./obscure.js";
+/** cli-core's layer, read after cli-base's and before the tool's. */
+export const CORE_CONSTANTS = new URL("../../constants.json", import.meta.url);
+/** What cli-base's and cli-core's layers hold; a tool extends it with `v.object({ ...constantsSchema.entries, … })`. */
+export const constantsSchema = v.object({
+    ...baseConstantsSchema.entries,
+    google: v.object({
+        app: v.object({
+            client_id: v.pipe(v.string(), v.nonEmpty(), v.transform(reveal)),
+            client_secret: v.optional(v.pipe(v.string(), v.transform(reveal))),
+        }),
+    }),
+    microsoft: v.object({ app: v.object({ client_id: v.pipe(v.string(), v.nonEmpty()) }) }),
+});
+const loaded = new Map();
+/**
+ * The packaged constants, base → core → the tool's `constants.json` when given, read once per process for each tool
+ * layer. A tool with constants of its own passes its layer and a schema built on `constantsSchema`; the first call for
+ * a layer decides its schema.
+ */
+export const constants = (toolLayer, schema) => {
+    const key = toolLayer?.href ?? "";
+    if (!loaded.has(key)) {
+        const layers = toolLayer ? [BASE_CONSTANTS, CORE_CONSTANTS, toolLayer] : [BASE_CONSTANTS, CORE_CONSTANTS];
+        loaded.set(key, loadConstants(layers, schema ?? constantsSchema));
+    }
+    return loaded.get(key);
+};
+/**
+ * The app a sign-in uses, first match wins (WC-SECR-25): `--client-id`, `<PREFIX>_<PROVIDER>_CLIENT_ID`, the account's
+ * `<provider>.client_id`, WireCat's app. A secret without any of the first three ids is a `configuration_error`.
+ * Undefined when nothing names an app and WireCat has none.
+ */
+export const oauthApp = (options) => {
+    const { env, prefix, provider } = options;
+    const name = `${prefix}_${provider.toUpperCase()}_CLIENT`;
+    const clientSecret = env[`${name}_SECRET`];
+    const own = [
+        [options.clientId, "flag"],
+        [env[`${name}_ID`], "env"],
+        [options.configClientId, "config"],
+    ];
+    const [clientId, source] = own.find(([id]) => id) ?? [];
+    if (clientId && source)
+        return app({ clientId, ...(clientSecret ? { clientSecret } : {}) }, source);
+    if (clientSecret)
+        throw new CliError("configuration_error", `${name}_SECRET is set without a client id; set ${name}_ID too, or unset it to use WireCat's app`, { reason: "sign-in.secret-without-id" });
+    const wirecat = options.wirecat;
+    if (!wirecat?.client_id)
+        return undefined;
+    return app({ clientId: wirecat.client_id, ...(wirecat.client_secret ? { clientSecret: wirecat.client_secret } : {}) }, "constants");
+};
+const app = (client, source) => ({ client: { ...client, source }, source });
+/**
+ * The Google Desktop app a sign-in uses: `--client-file`, then `oauthApp`'s order. Google treats a Desktop app's
+ * secret as public (https://developers.google.com/identity/protocols/oauth2/native-app), so WireCat's ships, obscured,
+ * in cli-core's constants.
+ */
+export const googleApp = (options) => {
+    const { clientFile, platform } = options;
+    if (clientFile)
+        return app(readClientFile(clientFile, platform ? { platform } : {}), "flag");
+    const wirecat = (options.constants ?? constants()).google.app;
+    return oauthApp({ ...options, provider: "google", wirecat });
+};
+/** WireCat's Microsoft app is a public client: it has an id and no secret. */
+export const microsoftApp = (options) => {
+    const wirecat = (options.constants ?? constants()).microsoft.app;
+    return oauthApp({ ...options, provider: "microsoft", wirecat });
+};
+/** `doctor`'s `oauth_client` for one provider: the app a new sign-in would use; doctor reads no keyring. */
+export const oauthClientReport = (app, reason) => app?.source
+    ? { client: app.source === "constants" ? "wirecat" : "own", source: app.source }
+    : { client: null, source: null, ...(reason ? { reason } : {}) };

package/dist/constants/obscure.d.ts

@@ -0,0 +1 @@
+export declare const reveal: (obscured: string) => string;

package/dist/constants/obscure.js

@@ -0,0 +1,9 @@
+import { createDecipheriv } from "node:crypto";
+// Not protection: anyone holding the package can reveal these. It keeps secret scanners and a casual read from
+// treating WireCat's public Desktop app as a leaked credential, as rclone does for its own app.
+const KEY = Buffer.from("d43012779aa2dded3e98092a3dbcf5d8980c564172f5ce0a5fd0574e5f740339", "hex");
+export const reveal = (obscured) => {
+    const bytes = Buffer.from(obscured, "base64url");
+    const decipher = createDecipheriv("aes-256-ctr", KEY, bytes.subarray(0, 16));
+    return Buffer.concat([decipher.update(bytes.subarray(16)), decipher.final()]).toString("utf8");
+};

package/dist/errors/reasons.js

@@ -33,6 +33,7 @@ const SIGN_IN = [
     ["sign-in.client-file-invalid", "configuration_error", "the file is not a Desktop app OAuth client JSON"],
     ["oauth.scope-missing", "permission_error", "the sign-in lacks a permission this command needs"],
     ["sign-in.client-rejected", "configuration_error", "the provider rejected the OAuth client"],
+    ["sign-in.secret-without-id", "configuration_error", "an OAuth client secret is set without its client id"],
 ];
 /** Reasons every CLI over a provider's API raises alike: gcal and drive today. */
 const PROVIDER_API = [

package/dist/oauth/index.d.ts

@@ -1,6 +1,6 @@
 export { type Authorization, type AuthorizeOptions, authorize } from "./authorize.js";
 export { type ClientFileOptions, readClientFile } from "./client-file.js";
 export { type SignInOptions, type TokenKeeper, type TokenKeeperOptions, type TokensOptions, tokenKeeper, } from "./keeper.js";
-export type { ExchangeContext, OAuthClient, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
+export type { AppSource, ExchangeContext, OAuthClient, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
 export { requestTokens, revokeToken, TOKEN_LOG_ALLOW, TOKEN_LOG_EVENT } from "./requests.js";
 export { type CredentialStorageOptions, credentialStorage, driveSessionCodec, type EncodeInput, oauthAccount, type StoredTokens, standardCodec, type TokenCodec, type TokenStorage, zoomTokenCodec, } from "./storage.js";

package/dist/oauth/provider.d.ts

@@ -3,7 +3,12 @@ import type { Logger } from "@wirecat/cli-base";
 export interface OAuthClient {
     clientId: string;
     clientSecret?: string;
+    /** Where the sign-in found the app (WC-SECR-25); saved with the entry, so `doctor` reports the app it used. */
+    source?: AppSource;
 }
+/** `flag`: `--client-file` or `--client-id`; `env`: `<TOOL>_<PROVIDER>_CLIENT_ID`; `config`: the account's
+ * `<provider>.client_id`; `constants`: WireCat's app. */
+export type AppSource = "flag" | "env" | "config" | "constants";
 export interface TokenSet {
     accessToken?: string;
     refreshToken: string;

package/dist/oauth/storage.js

@@ -40,8 +40,9 @@ export const standardCodec = (providerId) => ({
             throw invalid();
         if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
             throw invalid();
+        const source = text(value.clientSource);
         return {
-            client: { clientId },
+            client: defined({ clientId, clientSecret: text(value.clientSecret), source }),
             tokens: defined({
                 accessToken: text(value.accessToken),
                 refreshToken,
@@ -57,6 +58,10 @@ export const standardCodec = (providerId) => ({
         version: 1,
         provider: providerId,
         clientId: client.clientId,
+        // Only WireCat's secret, which is public: a later release may ship another default app, and a refresh needs
+        // the secret of the app that signed in. An owner's own secret stays where the owner keeps it.
+        clientSecret: client.source === "constants" ? client.clientSecret : undefined,
+        clientSource: client.source,
         accessToken: tokens.accessToken,
         refreshToken: tokens.refreshToken,
         expiresAt: tokens.expiresAt,
@@ -80,7 +85,11 @@ export const driveSessionCodec = {
         if (!refreshToken || !clientId || typeof value.principal !== "string")
             throw invalid();
         return {
-            client: defined({ clientId, clientSecret: text(value.clientSecret) }),
+            client: defined({
+                clientId,
+                clientSecret: text(value.clientSecret),
+                source: text(value.clientSource),
+            }),
             tokens: defined({
                 accessToken: text(fields.access_token),
                 refreshToken,
@@ -98,6 +107,7 @@ export const driveSessionCodec = {
             ...extra,
             clientId: client.clientId,
             ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+            ...(client.source ? { clientSource: client.source } : {}),
             tokens: defined({
                 ...oldTokens,
                 access_token: tokens.accessToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.565.0",
+  "version": "0.566.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -19,6 +19,7 @@
   "packageManager": "pnpm@11.28.8",
   "files": [
     "dist",
+    "constants.json",
     "parity.json",
     "skills",
     "README.md",
@@ -166,6 +167,10 @@
     "./oauth": {
       "types": "./dist/oauth/index.d.ts",
       "default": "./dist/oauth/index.js"
+    },
+    "./constants": {
+      "types": "./dist/constants/index.d.ts",
+      "default": "./dist/constants/index.js"
     }
   },
   "scripts": {
@@ -273,7 +278,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.75.0 <0.78.0",
+    "@wirecat/cli-base": ">=0.76.0 <0.78.0",
     "commander": ">=15"
   },
   "bin": {