@kanonak-protocol/cli 5.4.0 → 5.6.0

package/dist/auth/enrollment/EnrollmentFlow.d.ts

@@ -18,6 +18,9 @@ import type { FetchLike } from './IssuanceClient.js';
 /** The discovery capability the flow needs (satisfied by {@link OAuthDiscovery}). */
 export interface EnrollmentMetadataSource {
     discover(host: string): Promise<OAuthServerMetadata | null>;
+    /** Resolve a publisher to its authority issuer URL(s) via the always-public
+     *  RFC 9728 `oauth-protected-resource` document. */
+    discoverProtectedResource(host: string): Promise<string[] | null>;
 }
 /** Just enough of {@link CredentialStore} to reuse a stored OAuth client_id. */
 export interface CredentialLookup {
@@ -58,7 +61,7 @@ export declare class EnrollmentFlow {
     private readonly fetchImpl;
     private readonly openBrowser;
     constructor(deps?: EnrollmentFlowDeps);
-    enroll(host: string, opts: EnrollOptions): Promise<EnrollmentResult>;
+    enroll(publisher: string, opts: EnrollOptions): Promise<EnrollmentResult>;
     /** A stored OAuth client_id for the host, or a freshly dynamically-registered one. */
     private resolveClientId;
     /** Exchange an authorization code (PKCE) for the short-lived consent token. */

package/dist/capabilities/GenericCapabilityHandler.d.ts

@@ -63,10 +63,15 @@ export declare class GenericCapabilityHandler {
      */
     private deployFromDoc;
     /**
-     * On a "package not found" error, scan the publisher index for
-     * approximate name matches and print up to 5 suggestions. Helps
-     * users recover from typos and from passing a 3-segment URI to
-     * `add` against an old CLI that lacked instance support.
+     * A publisher's OWN packages as pinned by its served `kanonak.lock` (keys
+     * under `<publisher>/`). The lock-derived package list — there is no index
+     * enumeration. Empty when the publisher serves no lock.
+     */
+    private lockedOwnPackages;
+    /**
+     * On a "package not found" error, scan the publisher's pinned packages for
+     * approximate name matches and print up to 5 suggestions. Helps users recover
+     * from typos and from passing a 3-segment URI to `add`.
      */
     private printPackageSuggestions;
     remove(capability: LoadedCapability, name: string, options: Record<string, string>): Promise<void>;

package/dist/commands/connect.d.ts

@@ -0,0 +1,72 @@
+import type { LockFile, LockEntry, PublisherConfig, DeviceEnrollmentRecord, SessionRecord, AuthenticatedFetchFn } from '@kanonak-protocol/sdk';
+/** The outcome of a connect, for a host (CLI / VS Code) to report. */
+export interface ConnectResult {
+    connected: boolean;
+    enrolled: boolean;
+    installed: number;
+    /** A failure reason, or the sentinel `'aborted'` when the user declined the install. */
+    error?: string;
+}
+/**
+ * Injectable collaborators so `connect` runs identically across surfaces (CLI,
+ * VS Code) and is testable without network, a device, or stdin. Every field
+ * defaults to the real implementation.
+ */
+export interface ConnectDeps {
+    fetchFn?: AuthenticatedFetchFn;
+    /** Resolve a publisher to its authority via RFC 9728 oauth-protected-resource. */
+    discovery?: {
+        discoverProtectedResource(host: string): Promise<string[] | null>;
+    };
+    configResolver?: {
+        getConfig(host: string): Promise<PublisherConfig>;
+    };
+    deviceStore?: {
+        get(host: string): Promise<DeviceEnrollmentRecord | null>;
+    };
+    publisherIndex?: {
+        getLock(host: string): Promise<LockFile | null>;
+    };
+    sessionManager?: {
+        getValidSession(host: string): Promise<SessionRecord | null>;
+    };
+    /** Run device enrollment for a publisher (resolves its authority internally). */
+    enroll?: (publisher: string) => Promise<{
+        success: boolean;
+        thumbprint?: string;
+        error?: string;
+    }>;
+    /** Fetch + verify + cache one pinned package. */
+    installEntry?: (publisher: string, packageName: string, entry: LockEntry) => Promise<void>;
+    loadLock?: () => LockFile | null;
+    saveLock?: (lock: LockFile) => void;
+    /** Ask the user to confirm the install. The host supplies its own prompt. */
+    confirm?: (question: string) => Promise<boolean>;
+    /** Progress output sink. */
+    log?: (message: string) => void;
+}
+/**
+ * The `connect` orchestrator core (issue #9): given a publisher domain, learn
+ * whether it is gated from the always-public RFC 9728 `oauth-protected-resource`
+ * document, enroll this device if it is gated and not already enrolled, then
+ * read the publisher's `kanonak.json` (its `featured_packages`) and install them
+ * and their pinned closures from the served `kanonak.lock`.
+ *
+ * For a gated publisher the `kanonak.json`/`kanonak.lock` are themselves behind
+ * auth, so those reads go through the device session minted from the enrolled
+ * cert. A public publisher (no `oauth-protected-resource`) never enrolls and
+ * reads everything anonymously. Pure of process/stdout concerns — returns a
+ * {@link ConnectResult} and reports via `deps.log`.
+ */
+export declare function connect(publisher: string, options: {
+    install?: boolean;
+    yes?: boolean;
+}, deps?: ConnectDeps): Promise<ConnectResult>;
+/**
+ * `kanonak connect <publisher>` — the CLI wrapper: console output, a stdin
+ * confirmation prompt, and a non-zero exit on failure.
+ */
+export declare function connectCommand(publisher: string, options: {
+    install?: boolean;
+    yes?: boolean;
+}): Promise<void>;

package/dist/commands/install.d.ts

@@ -1,8 +1,33 @@
+import { KanonakParser } from '@kanonak-protocol/sdk';
+import type { AuthenticatedFetchFn } from '@kanonak-protocol/sdk';
+import type { LockFile, LockEntry } from '@kanonak-protocol/sdk';
+import { FileCache } from '../cache/FileCache.js';
 /**
  * Install a package and its transitive dependencies to the local cache.
  *
- * Usage: kanonak install kanonak.org/core-rdf@1.0.1
- *        kanonak install kanonak.org/core-rdf  (resolves latest compatible)
- *        kanonak install                              (install from kanonak.lock)
+ * Resolution flows through the publisher's SERVED `kanonak.lock` — the
+ * authoritative, integrity-verified closure (one pinned version per package).
+ * Installing `publisher/package` installs exactly the version that lock pins
+ * plus the closure it pins, verifying every fetched file against the lock's
+ * sha256 before caching (the `npm ci` model). There is no version-range
+ * selection: the publisher's lock IS the resolution.
+ *
+ * Usage: kanonak install kanonak.org/core-rdf      (install what the lock pins)
+ *        kanonak install kanonak.org/core-rdf@1.0.1 (must match the pinned version)
+ *        kanonak install                            (install from the local kanonak.lock)
  */
 export declare function installCommand(packageRef?: string): Promise<void>;
+/**
+ * Ensure a pinned package is in the cache: a cache hit is verified against the
+ * lock's integrity; a miss is fetched from the entry's `resolved` URL, verified,
+ * identity-checked, then cached. Never caches bytes whose hash or namespace
+ * disagrees with the lock — a mismatch throws.
+ */
+export declare function fetchVerifyCache(publisher: string, packageName: string, entry: LockEntry, fileCache: FileCache, parser: KanonakParser, fetchFn: AuthenticatedFetchFn): Promise<void>;
+/**
+ * The keys of `rootKey` and every package reachable through its (transitive)
+ * `dependencies`, all resolved within `lock`. A dependency the lock references
+ * but does not pin is a broken lock — throw rather than silently install a
+ * partial closure.
+ */
+export declare function collectClosure(rootKey: string, lock: LockFile): string[];