@holokai/harbor-sdk 0.5.0 → 0.6.0-rc.0

package/dist/build-inputs.json

@@ -1,6 +1,6 @@
 {
   "package": "@holokai/harbor-sdk",
-  "version": "0.5.0",
-  "digest": "cc9eed9b0678ea2d2300006bdf45b0dbf1dec99eff125a9c7d22133db1f99a9e",
-  "commit": "acdb1a6f7bb8a8e52334cc4e7f45729a406bb09e"
+  "version": "0.6.0-rc.0",
+  "digest": "ee14f279ce9678445cfa96aca7c3c14e5a2ed36ad5f7ba0586d49f3a61aa36a8",
+  "commit": "86e86d6f6f6131ff2d8bc9117e165d3f9000f8a2"
 }

package/dist/manifest.d.ts

@@ -1,4 +1,4 @@
-/** The manifest type a first-party extension exports and harbor reads. */
+/** The manifest a first-party extension exports and harbor reads, and the helpers that declare its sign-in client. */
 import type { DeclaredGrant } from './contract';
 /** An image for an extension, the MCP `Icon` shape; `src` is a data: URL. */
 export interface ExtensionIcon {
@@ -6,6 +6,18 @@ export interface ExtensionIcon {
     mimeType?: string;
     sizes?: string[];
 }
+/**
+ * Where a provider's confidential client trades a code: the one address an organization's client secret is sent to.
+ * Every extension of one provider declares the same one.
+ */
+export interface SignInDeclaration {
+    /** The vendor's token endpoint, https. */
+    token: string;
+    /** The setting holding the client id, one of `settings`. */
+    clientId: string;
+    /** The setting holding the client secret, one of `secretSettings`. */
+    clientSecret: string;
+}
 /** Who an extension is: what harbor shows for it and what it needs to run. */
 export interface ExtensionManifest {
     /** The path segment it is served at, lowercase letters, digits and dashes, starting with a letter. */
@@ -21,6 +33,23 @@ export interface ExtensionManifest {
     icon?: ExtensionIcon;
     /** The names of the settings it reads from its environment, such as `MICROSOFT_CLIENT_ID`. */
     settings: readonly string[];
+    /** Which of `settings` are secret: shown masked, and never logged. */
+    secretSettings?: readonly string[];
+    /** A label for each setting, for an organization's admin. */
+    settingLabels?: Readonly<Record<string, string>>;
+    /** Where its sign-in client trades a code, for a provider with a confidential client. */
+    signIn?: SignInDeclaration;
     /** The grants harbor gives only to an extension that names them, such as `files.add`. */
     grants?: readonly DeclaredGrant[];
 }
+/** One field of a provider's sign-in client, as the manifest needs it: the kit's `ClientField` fits. */
+export interface ManifestClientField {
+    name: string;
+    label: string;
+    secret: boolean;
+    env: string;
+}
+/** The manifest's settings for a provider's client: their names, which are secret, and their labels. */
+export declare function clientSettings(fields: readonly ManifestClientField[]): Pick<ExtensionManifest, 'settings' | 'secretSettings' | 'settingLabels'>;
+/** A confidential client's sign-in: `token`, and the settings of its `clientId` and `clientSecret` fields. */
+export declare function signInDeclaration(token: string, fields: readonly ManifestClientField[]): SignInDeclaration;

package/dist/manifest.js

@@ -1 +1,23 @@
 import {createRequire as __harborCreateRequire} from 'node:module'; const require = __harborCreateRequire(import.meta.url);
+
+// src/manifest.ts
+function clientSettings(fields) {
+  const secret = fields.filter((field) => field.secret).map((field) => field.env);
+  return {
+    settings: fields.map((field) => field.env),
+    ...secret.length === 0 ? {} : { secretSettings: secret },
+    settingLabels: Object.fromEntries(fields.map((field) => [field.env, field.label]))
+  };
+}
+function signInDeclaration(token, fields) {
+  const env = (name, secret) => {
+    const field = fields.find((candidate) => candidate.name === name && candidate.secret === secret);
+    if (field === void 0) throw new Error(`a sign-in client needs a ${secret ? "secret " : ""}${name} field`);
+    return field.env;
+  };
+  return { token, clientId: env("clientId", false), clientSecret: env("clientSecret", true) };
+}
+export {
+  clientSettings,
+  signInDeclaration
+};

package/dist/package.d.ts

@@ -3,7 +3,7 @@
  * It imports nothing at run time, so Harbor's main process, the extension host and the build scripts all read it.
  */
 import type { DeclaredGrant } from './contract';
-import type { ExtensionManifest } from './manifest';
+import type { ExtensionIcon, ExtensionManifest, SignInDeclaration } from './manifest';
 /** The extension-to-host API version. A host runs only extensions that declare it. */
 export declare const EXTENSION_API_VERSION = 1;
 /** The `harbor` field of a published package's package.json: which kind of package it is. */
@@ -119,12 +119,23 @@ export type ReleaseTarget = (typeof RELEASE_TARGETS)[number];
 /** The lanes a release manifest is published on. */
 export declare const RELEASE_LANES: readonly ["production", "beta"];
 export type ReleaseLane = (typeof RELEASE_LANES)[number];
-/** One extension a release set holds. */
+/**
+ * One extension a release set holds. The fields after `grants` are optional, so a record without them, older or
+ * newer, still parses; an organization's Moku reads them to manage the extension's settings.
+ */
 export interface ReleaseSetExtension {
     version: string;
     /** The provider decides the process, and so the shared sign-in, the extension runs in. */
     provider: string;
     grants: readonly DeclaredGrant[];
+    title?: string;
+    description?: string;
+    /** The extension's own icon, from its manifest, so a reader shows it without opening an archive. */
+    icon?: ExtensionIcon;
+    settings?: readonly string[];
+    secretSettings?: readonly string[];
+    settingLabels?: Readonly<Record<string, string>>;
+    signIn?: SignInDeclaration;
 }
 /** One target's archive of a release set. */
 export interface ReleaseArtifact {
@@ -185,6 +196,8 @@ export declare const laneManifestKey: (lane: ReleaseLane, sequence: number) => s
 export declare const laneSignatureKey: (lane: ReleaseLane, sequence: number) => string;
 /** The store key of a lane's pointer, the one object in the store that is replaced. */
 export declare const lanePointerKey: (lane: ReleaseLane) => string;
+/** A set record's entry for an extension, from its installed manifest and version. */
+export declare function setRecordExtension(manifest: ExtensionManifest, version: string): ReleaseSetExtension;
 /** A set record, or null when any field is out of shape. Only ReleaseSet's fields survive. */
 export declare function parseReleaseSet(value: unknown): ReleaseSet | null;
 /** A lane manifest, or null when it or any set it lists is out of shape, or it lists one set id twice. */
@@ -221,15 +234,22 @@ export declare function incompatibility(set: ReleaseSet, here: {
     running: Record<string, string>;
 }): Incompatibility | null;
 /** Why a release policy refuses a set that is protocol-compatible. */
-export type PolicyRefusal = 'new_extension' | 'removed_extension' | 'changes_provider' | 'organization';
+export type PolicyRefusal = 'new_extension' | 'removed_extension' | 'changes_provider' | 'changes_sign_in_authority' | 'sign_ins_disagree' | 'organization';
 /** Rollout and organization policy, apart from protocol. */
 export interface ExtensionReleasePolicy {
     /** The reason the set may not replace the running extensions, or null when it may. */
     refusal(set: ReleaseSet, running: ReleaseSet['extensions']): PolicyRefusal | null;
 }
 /**
- * The first-party default: a set that adds an extension, drops one the running tree holds, or moves one to another
- * provider waits for an app release.
+ * Whether a set's sign-ins agree: every extension of one provider declares the same `signIn`, since a provider is
+ * one process and one sign-in, and a setting name belongs to one provider, so an organization's value for it reaches
+ * one sign-in. The publisher refuses to build a set that breaks this, and Harbor refuses to install one.
+ */
+export declare function signInsAgree(extensions: Readonly<Record<string, ReleaseSetExtension>>): boolean;
+/**
+ * The first-party default: a set that adds an extension, drops one the running tree holds, moves one to another
+ * provider, or changes where one's sign-in client trades a code (the address an organization's client secret goes
+ * to) waits for an app release. A set whose sign-ins disagree is never installed.
  */
 export declare const FIRST_PARTY_ROLLOUT: ExtensionReleasePolicy;
 /** The grants of `declared` that `authorized` holds, by stable id; the rest are withheld. */

package/dist/package.js

@@ -28,6 +28,36 @@ function parseIcon(value) {
     ...value.sizes === void 0 ? {} : { sizes: [...value.sizes] }
   };
 }
+function parseSettingFields(settings, value) {
+  const { secretSettings, settingLabels, signIn } = value;
+  if (secretSettings !== void 0 && !(isStringArray(secretSettings) && secretSettings.every((n) => settings.includes(n)))) {
+    return null;
+  }
+  if (settingLabels !== void 0 && !(isRecord(settingLabels) && Object.entries(settingLabels).every(([n, l]) => settings.includes(n) && isString(l)))) {
+    return null;
+  }
+  let parsedSignIn;
+  if (signIn !== void 0) {
+    if (!isRecord(signIn) || !isString(signIn.token) || !isString(signIn.clientId) || !isString(signIn.clientSecret)) {
+      return null;
+    }
+    if (!isHttps(signIn.token) || !settings.includes(signIn.clientId)) return null;
+    if (!secretSettings?.includes(signIn.clientSecret)) return null;
+    parsedSignIn = { token: signIn.token, clientId: signIn.clientId, clientSecret: signIn.clientSecret };
+  }
+  return {
+    ...secretSettings === void 0 ? {} : { secretSettings: [...secretSettings] },
+    ...settingLabels === void 0 ? {} : { settingLabels: { ...settingLabels } },
+    ...parsedSignIn === void 0 ? {} : { signIn: parsedSignIn }
+  };
+}
+function isHttps(value) {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 function parseExtensionManifest(value) {
   if (!isRecord(value)) return null;
   const { name, title, description, version, provider, icon, settings, grants } = value;
@@ -40,6 +70,8 @@ function parseExtensionManifest(value) {
   if (grants !== void 0 && !(isStringArray(grants) && grants.every((grant) => DECLARED_GRANTS.has(grant)))) {
     return null;
   }
+  const settingFields = parseSettingFields(settings, value);
+  if (settingFields === null) return null;
   return {
     name,
     title,
@@ -48,6 +80,7 @@ function parseExtensionManifest(value) {
     provider,
     ...parsedIcon === void 0 ? {} : { icon: parsedIcon },
     settings: [...settings],
+    ...settingFields,
     ...grants === void 0 ? {} : { grants: [...grants] }
   };
 }
@@ -164,10 +197,39 @@ var laneSignatureKey = (lane, sequence) => `${laneManifestKey(lane, sequence)}.s
 var lanePointerKey = (lane) => `extensions/lanes/${lane}/latest.json`;
 function parseSetExtension(value) {
   if (!isRecord(value)) return null;
-  const { version, provider, grants } = value;
+  const { version, provider, grants, title, description, icon, settings } = value;
   if (!isString(version) || !isVersion(version) || !isString(provider) || !NAME.test(provider)) return null;
   if (!isStringArray(grants) || !grants.every((grant) => DECLARED_GRANTS.has(grant))) return null;
-  return { version, provider, grants: [...grants] };
+  if (title !== void 0 && !isString(title) || description !== void 0 && !isString(description)) return null;
+  const parsedIcon = icon === void 0 ? void 0 : parseIcon(icon);
+  if (parsedIcon === null) return null;
+  if (settings !== void 0 && !isStringArray(settings)) return null;
+  const settingFields = parseSettingFields(settings ?? [], value);
+  if (settingFields === null) return null;
+  return {
+    version,
+    provider,
+    grants: [...grants],
+    ...title === void 0 ? {} : { title },
+    ...description === void 0 ? {} : { description },
+    ...parsedIcon === void 0 ? {} : { icon: parsedIcon },
+    ...settings === void 0 ? {} : { settings: [...settings] },
+    ...settingFields
+  };
+}
+function setRecordExtension(manifest, version) {
+  return {
+    version,
+    provider: manifest.provider,
+    grants: [...manifest.grants ?? []],
+    title: manifest.title,
+    description: manifest.description,
+    ...manifest.icon === void 0 ? {} : { icon: { ...manifest.icon } },
+    settings: [...manifest.settings],
+    ...manifest.secretSettings === void 0 ? {} : { secretSettings: [...manifest.secretSettings] },
+    ...manifest.settingLabels === void 0 ? {} : { settingLabels: { ...manifest.settingLabels } },
+    ...manifest.signIn === void 0 ? {} : { signIn: { ...manifest.signIn } }
+  };
 }
 function parseArtifact(value, id, target) {
   if (!isRecord(value)) return null;
@@ -290,12 +352,33 @@ function incompatibility(set, here) {
   if (set.artifacts[here.target] === void 0) return "no_artifact";
   return null;
 }
+var sameSignIn = (a, b) => a?.token === b?.token && a?.clientId === b?.clientId && a?.clientSecret === b?.clientSecret;
+function signInsAgree(extensions) {
+  const signIns = /* @__PURE__ */ new Map();
+  const owners = /* @__PURE__ */ new Map();
+  for (const extension of Object.values(extensions)) {
+    if (signIns.has(extension.provider) && !sameSignIn(signIns.get(extension.provider), extension.signIn)) {
+      return false;
+    }
+    signIns.set(extension.provider, extension.signIn);
+    for (const setting of extension.settings ?? []) {
+      if ((owners.get(setting) ?? extension.provider) !== extension.provider) return false;
+      owners.set(setting, extension.provider);
+    }
+  }
+  return true;
+}
 var FIRST_PARTY_ROLLOUT = {
   refusal(set, running) {
+    if (!signInsAgree(set.extensions)) return "sign_ins_disagree";
     if (Object.keys(set.extensions).some((name) => running[name] === void 0)) return "new_extension";
     if (Object.keys(running).some((name) => set.extensions[name] === void 0)) return "removed_extension";
     const moved = Object.entries(set.extensions).some(([name, ext]) => running[name]?.provider !== ext.provider);
-    return moved ? "changes_provider" : null;
+    if (moved) return "changes_provider";
+    const authorityMoved = Object.entries(set.extensions).some(
+      ([name, ext]) => !sameSignIn(running[name]?.signIn, ext.signIn)
+    );
+    return authorityMoved ? "changes_sign_in_authority" : null;
   }
 };
 function authorizedGrants(declared, authorized) {
@@ -332,5 +415,7 @@ export {
   satisfiesCaret,
   setArchiveKey,
   setLockfileKey,
-  setRecordKey
+  setRecordExtension,
+  setRecordKey,
+  signInsAgree
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holokai/harbor-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0-rc.0",
   "type": "module",
   "description": "The harbor extension to MCP Apps: the public contract a hosted view speaks, and a thin client over @modelcontextprotocol/ext-apps.",
   "exports": {