@kanonak-protocol/cli 5.9.0 → 5.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanonak-protocol/cli",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "description": "Command-line tool for the Kanonak Protocol — validate, resolve, preview, and publish semantic ontology packages.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,12 +35,10 @@
     "semantic-web"
   ],
   "dependencies": {
-    "@kanonak-protocol/sdk": "^5.9.0",
-    "@kanonak-protocol/types": "^5.9.0",
-    "@peculiar/x509": "^2.0.0",
+    "@kanonak-protocol/sdk": "^5.10.0",
+    "@kanonak-protocol/types": "^5.10.0",
     "commander": "^13.0.0",
-    "js-yaml": "^4.1.1",
-    "reflect-metadata": "^0.2.2"
+    "js-yaml": "^4.1.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

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

@@ -1,13 +0,0 @@
-import 'reflect-metadata';
-import type { DeviceKey } from './KeyProvider.js';
-export interface CsrResult {
-    /** The CSR in PEM form (`-----BEGIN CERTIFICATE REQUEST-----`). */
-    csrPem: string;
-    /** The device key's RFC 7638 thumbprint (echoes {@link DeviceKey.thumbprint}). */
-    thumbprint: string;
-}
-/**
- * Build and sign a CSR for `deviceKey`. `subjectCommonName` becomes the CSR
- * subject CN (advisory). Signed with ECDSA / SHA-256.
- */
-export declare function buildCsr(deviceKey: DeviceKey, subjectCommonName: string): Promise<CsrResult>;

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

@@ -1,69 +0,0 @@
-import 'reflect-metadata';
-import type { DeviceEnrollmentRecord } from '@kanonak-protocol/sdk';
-import type { OAuthServerMetadata } from '@kanonak-protocol/sdk';
-import type { KeyProvider, KeyType } from './KeyProvider.js';
-import type { FetchLike } from './IssuanceClient.js';
-/**
- * Device-certificate enrollment flow (issue #67, Phase 1).
- *
- * discover → generate a device key → build a CSR → run Authorization Code + PKCE
- * over a 127.0.0.1 loopback redirect (RFC 7636 / 8252) with the CSR key's RFC
- * 7638 thumbprint bound into the consent (anti-substitution) → exchange the code
- * for a consent token → submit the CSR to the discovered native issuance
- * endpoint → install the signed certificate in the device store.
- *
- * Collaborators are injectable so the flow is testable end-to-end against a
- * mock authorization server + CA without a real browser.
- */
-/** 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 {
-    getCredential(host: string): Promise<{
-        clientId?: string | null;
-    } | null>;
-}
-/** Just enough of {@link DeviceCertificateStore} to install the enrollment. */
-export interface DeviceStoreLike {
-    store(host: string, record: DeviceEnrollmentRecord): Promise<void>;
-}
-export interface EnrollmentFlowDeps {
-    discovery?: EnrollmentMetadataSource;
-    credentialStore?: CredentialLookup;
-    deviceStore?: DeviceStoreLike;
-    keyProvider?: KeyProvider;
-    /** HTTP for DCR / token exchange / CSR issuance (injectable for tests). */
-    fetchImpl?: FetchLike;
-    /** Drives the user's consent step; defaults to opening the system browser. */
-    openBrowser?: (url: string) => void;
-}
-export interface EnrollOptions {
-    scopes: string[];
-    keyType?: KeyType;
-    deviceName?: string;
-}
-export interface EnrollmentResult {
-    success: boolean;
-    host?: string;
-    thumbprint?: string;
-    error?: string;
-}
-export declare class EnrollmentFlow {
-    private readonly discovery;
-    private readonly credentialStore;
-    private readonly deviceStore;
-    private readonly keyProvider;
-    private readonly fetchImpl;
-    private readonly openBrowser;
-    constructor(deps?: EnrollmentFlowDeps);
-    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. */
-    private exchangeCode;
-}

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

@@ -1,43 +0,0 @@
-/**
- * The "a CA signs the CSR" role of the provider-agnostic enrollment contract
- * (issue #67), behind an interface so multiple issuance protocols sit behind one
- * abstraction. v1 ships the {@link NativeIssuanceClient} (the OIDC-provisioner
- * shape — submit the CSR with the consent token, the CA signs it; this is the
- * industry best practice for consented device enrollment, per Smallstep /
- * Tailscale / Teleport). EST (RFC 7030) and ACME (RFC 8555) adapters are later
- * additions behind the same interface.
- */
-export interface IssuanceContext {
-    /** The registry host being enrolled with. */
-    host: string;
-    /** Scopes consented for the certificate. */
-    scopes: string[];
-    /** Human-facing device label. */
-    deviceName?: string;
-}
-export interface IssuedCertificate {
-    /** The CA-signed leaf certificate (PEM). */
-    certificatePem: string;
-    /** The issuing chain (PEM), or '' if the server returns none. */
-    chainPem: string;
-}
-export interface IssuanceClient {
-    /** The issuance protocol this adapter implements, e.g. `native`. */
-    readonly protocol: string;
-    /** Submit a CSR for signing, authorized by the consent token. */
-    enroll(csrPem: string, consentToken: string, ctx: IssuanceContext): Promise<IssuedCertificate>;
-}
-/** A minimal fetch signature so tests can inject a localhost client. */
-export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
-/**
- * Native issuance: POST the CSR + consent token (as a bearer) to the discovered
- * enrollment endpoint; the endpoint verifies the consent (incl. the bound key
- * thumbprint), signs the CSR, and returns `{ certificate, chain }`.
- */
-export declare class NativeIssuanceClient implements IssuanceClient {
-    private readonly enrollmentEndpoint;
-    private readonly fetchImpl;
-    readonly protocol = "native";
-    constructor(enrollmentEndpoint: string, fetchImpl: FetchLike);
-    enroll(csrPem: string, consentToken: string, ctx: IssuanceContext): Promise<IssuedCertificate>;
-}

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

@@ -1,55 +0,0 @@
-import { webcrypto } from 'node:crypto';
-type JsonWebKey = webcrypto.JsonWebKey;
-type CryptoKeyPair = webcrypto.CryptoKeyPair;
-/**
- * Device key custody, behind a pluggable provider (issue #67).
- *
- * v1 ships {@link SoftwareKeyProvider} (a WebCrypto EC P-256 key, persisted as a
- * JWK in the OS-secure device store). The interface is shaped so a hardware
- * provider — PKCS#11 / Secure Enclave / TPM-CNG, where the private key never
- * leaves the token — drops in unchanged: the CSR builder and token minting only
- * ever touch the `CryptoKey` signing handle, never raw key bytes. This is the
- * Smallstep `step` / Teleport `tsh` key-provider pattern, scoped to Node.
- */
-/** The device key types the contract recognizes. v1 implements `ec-p256`. */
-export type KeyType = 'ec-p256';
-/** A device-held key: a signing handle plus the public material needed for a CSR. */
-export interface DeviceKey {
-    readonly keyType: KeyType;
-    /** The public key as a JWK (goes into the CSR / record; never secret). */
-    readonly publicKeyJwk: JsonWebKey;
-    /** RFC 7638 JWK SHA-256 thumbprint of the public key — the consent-bound identity. */
-    readonly thumbprint: string;
-    /** The key pair handle used to sign the CSR (and later mint tokens). */
-    readonly keyPair: CryptoKeyPair;
-    /**
-     * Serialize the key for the device store. Software: the private JWK.
-     * A hardware provider returns an opaque handle (no exportable key bytes).
-     */
-    exportKeyMaterial(): Promise<Record<string, unknown>>;
-}
-export interface KeyProvider {
-    /** Stable id recorded with the enrollment, e.g. `software`, `pkcs11`. */
-    readonly id: string;
-    /** Generate a fresh non-shared device key of the given type. */
-    generate(keyType: KeyType): Promise<DeviceKey>;
-    /** Re-hydrate a {@link DeviceKey} from previously stored key material. */
-    importKeyMaterial(material: Record<string, unknown>, keyType: KeyType): Promise<DeviceKey>;
-}
-/**
- * Software EC P-256 key provider. The private key is extractable so it can be
- * persisted across CLI invocations (and used later to mint tokens) — the
- * deliberate v1 tradeoff that a future hardware provider removes.
- */
-export declare class SoftwareKeyProvider implements KeyProvider {
-    readonly id = "software";
-    generate(keyType: KeyType): Promise<DeviceKey>;
-    importKeyMaterial(material: Record<string, unknown>, keyType: KeyType): Promise<DeviceKey>;
-}
-/**
- * RFC 7638 JWK SHA-256 thumbprint (base64url). For an EC key the canonical
- * member set is `{crv, kty, x, y}` in lexical order — the same thumbprint DPoP's
- * `jkt` uses, so the binding is a well-known construction.
- */
-export declare function jwkThumbprint(jwk: JsonWebKey): Promise<string>;
-export {};

package/dist/auth/oauthHelpers.d.ts

@@ -1,37 +0,0 @@
-/**
- * Reusable OAuth 2.0 / RFC 8252 native-app helpers: the loopback callback
- * server, PKCE (RFC 7636) generation, the authorization-URL builder, and the
- * system browser opener. `EnrollmentFlow` (device enrollment) builds on these so
- * the loopback + PKCE mechanics live in exactly one place.
- */
-export declare function generateCodeVerifier(): string;
-export declare function generateCodeChallenge(verifier: string): string;
-export declare function generateState(): string;
-/**
- * Build an authorization-code + PKCE-S256 request URL. `extraParams` carries
- * flow-specific bindings — e.g. device enrollment adds the CSR key thumbprint so
- * consent authorizes that specific key (anti-substitution).
- */
-export declare function buildAuthorizationUrl(opts: {
-    endpoint: string;
-    clientId: string;
-    redirectUri: string;
-    scopes: string[];
-    state: string;
-    codeChallenge: string;
-    extraParams?: Record<string, string>;
-}): string;
-export interface CallbackResult {
-    code?: string;
-    state?: string;
-    error?: string;
-}
-export declare const CALLBACK_TIMEOUT_MS: number;
-export declare function startCallbackServer(): Promise<{
-    redirectUri: string;
-    port: number;
-    waitForCallback: () => Promise<CallbackResult | null>;
-    close: () => void;
-}>;
-export declare function escapeHtml(str: string): string;
-export declare function openBrowser(url: string): void;

package/dist/auth/publisherAuthority.d.ts

@@ -1,38 +0,0 @@
-import { DeviceCertificateStore } from '@kanonak-protocol/sdk';
-/**
- * Publisher-centric authority resolution — the ONE way every CLI command turns
- * what the user typed into the authority that actually keys an enrollment /
- * session.
- *
- * Users think in PUBLISHERS (`paul.kanonak.com`) — the domain they `connect`,
- * `enroll`, `install` from. But device certs and the sessions minted from them
- * are keyed by the AUTHORITY (`oauth--paul.kanonak.com`), which the user neither
- * knows nor should have to type. The mapping is the enrollment record's
- * `publisher` field, captured at `connect`/`enroll` time. These helpers read it
- * (and fall back to RFC 9728 discovery) so `session login/token/logout/status`,
- * `device show/remove`, etc. all speak the publisher domain.
- */
-export interface PublisherAuthorityDeps {
-    store?: Pick<DeviceCertificateStore, 'get' | 'list'>;
-    discovery?: {
-        discoverProtectedResource(host: string): Promise<string[] | null>;
-    };
-}
-/**
- * Resolve the locally-enrolled AUTHORITY for what the user typed. Order:
- *   1. Direct — the input is already an enrolled authority key (e.g. copied
- *      from `device list`/`session status`).
- *   2. Local mapping — an enrollment recorded this publisher; resolve with no
- *      network call (the publisher-centric fast path).
- *   3. Network fallback — resolve the publisher to its authority via RFC 9728
- *      `oauth-protected-resource` (covers enrollments made before the publisher
- *      was recorded).
- * Returns the authority host that has a local enrollment, or null.
- */
-export declare function resolveEnrolledAuthority(input: string, deps?: PublisherAuthorityDeps): Promise<string | null>;
-/**
- * The publisher an enrolled authority was connected through, if it was recorded
- * — for presenting authority-keyed state (sessions) in publisher terms. Returns
- * undefined when the authority isn't enrolled locally or carries no publisher.
- */
-export declare function publisherForAuthority(authority: string, deps?: PublisherAuthorityDeps): Promise<string | undefined>;

package/dist/auth/session/GitCredentialHelper.d.ts

@@ -1,47 +0,0 @@
-import { type CredentialResolverDeps } from '@kanonak-protocol/sdk';
-/**
- * `kanonak` as a git credential helper (issue #72). Git invokes the helper per
- * request; for a Kanonak-credentialed repository host it returns a freshly-valid
- * session token, so pushes/pulls just work without static, expiring files.
- *
- * The actual resolution (RFC 9728 host→authority, then the authority-scoped
- * device session) lives in the SDK's CredentialResolver — the durable primitive.
- * This class owns only the git-specific concerns: the stdin/stdout protocol and
- * the HTTP Basic user-id. Self-filtering: when the resolver declines (no Kanonak
- * authority, or unenrolled), the helper emits nothing and git falls through.
- * Identity is never inferred; the Basic user-id is an RFC 7617 carrier (the token
- * is the credential).
- */
-/** A git credential description (the key=value lines git sends on stdin). */
-export interface GitCredential {
-    protocol?: string;
-    host?: string;
-    path?: string;
-    username?: string;
-    [key: string]: string | undefined;
-}
-export interface GitCredentialHelperDeps extends CredentialResolverDeps {
-    /** Carrier user-id when git's request supplies none (RFC 7617; not an identity). */
-    carrierUserId?: string;
-}
-export declare class GitCredentialHelper {
-    private readonly resolver;
-    private readonly carrier;
-    constructor(deps?: GitCredentialHelperDeps);
-    /**
-     * Resolve a git request to credentials, or null to DECLINE (git falls through).
-     */
-    resolve(cred: GitCredential): Promise<{
-        username: string;
-        password: string;
-    } | null>;
-    /**
-     * Run one git credential-helper invocation: parse the request from `input`,
-     * handle the operation, and return the stdout to emit ('' = decline). Only
-     * `get` produces credentials; `store`/`erase` are no-ops because Kanonak
-     * sessions are managed by `kanonak session`, not by git.
-     */
-    run(operation: string, input: string): Promise<string>;
-}
-/** Parse git's credential stdin: `key=value` lines, blank-line terminated. */
-export declare function parseGitCredential(input: string): GitCredential;

package/dist/auth/sessionFetch.d.ts

@@ -1,21 +0,0 @@
-import { CredentialResolver } from '@kanonak-protocol/sdk';
-import type { AuthenticatedFetchFn } from '@kanonak-protocol/sdk';
-/**
- * A fetch transport that authenticates GATED reads with the device session.
- *
- * Per host, it resolves the publisher → authority → device session
- * (CredentialResolver) and presents the session token as `Authorization: Bearer`.
- * A public publisher resolves to no credential and the request goes out
- * anonymously. This is what makes `install` / `connect` read a gated publisher's
- * `kanonak.json` / `kanonak.lock` / package sources — without it, those requests
- * hit the gate unauthenticated.
- *
- * Crucially it uses `redirect: 'manual'`: a gated endpoint 302-redirects an
- * unauthenticated request (e.g. to a login), and Node's default auto-following
- * turns that into a redirect LOOP. Not following means a gated 302 surfaces as a
- * clean non-OK response the caller reports, instead of spinning.
- *
- * The resolved credential is cached per host so one `connect`/`install` doesn't
- * re-mint a session for every package in the closure.
- */
-export declare function createSessionFetch(resolver?: CredentialResolver): AuthenticatedFetchFn;

package/dist/commands/connect.d.ts

@@ -1,69 +0,0 @@
-import type { LockFile, LockEntry, PublisherConfig, DeviceEnrollmentRecord, 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>;
-    };
-    /** 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/credential.d.ts

@@ -1,10 +0,0 @@
-import { Command } from 'commander';
-/**
- * `kanonak credential resolve <host>` — the durable host→credential primitive
- * (issue #72), exposed for scripting. Given any registry/repo host, it resolves
- * a freshly-valid credential (via RFC 9728 discovery + the authority-scoped
- * device session) and prints it as JSON, or exits non-zero when Kanonak has none
- * for that host. This is the same resolver the git credential helper uses; other
- * tooling builds on it instead of reimplementing the auth.
- */
-export declare function credentialCommand(): Command;

package/dist/commands/credentialHelper.d.ts

@@ -1,10 +0,0 @@
-import { Command } from 'commander';
-/**
- * `kanonak credential-helper <get|store|erase>` — a git credential helper
- * (issue #72). Git invokes it (configured via `credential.helper = !kanonak
- * credential-helper`), passing the credential description on stdin. For a
- * repository host that advertises a Kanonak authority (RFC 9728), it returns a
- * freshly-refreshed session token; for any other host it prints nothing, so git
- * falls through to its normal flow. Not meant to be run by hand.
- */
-export declare function credentialHelperCommand(): Command;

package/dist/commands/device.d.ts

@@ -1,9 +0,0 @@
-import 'reflect-metadata';
-import { Command } from 'commander';
-/**
- * `kanonak device` — manage device certificates for registry authentication
- * (issue #67). `enroll` generates a device-held key, builds a CSR, runs a
- * consent-bound SSO flow, and installs the CA-signed certificate; `list`,
- * `show`, and `remove` inspect and manage what was installed locally.
- */
-export declare function deviceCommand(): Command;

package/dist/commands/session.d.ts

@@ -1,24 +0,0 @@
-import { Command } from 'commander';
-/**
- * `kanonak session` — turn an enrolled device certificate into scoped,
- * auto-refreshing registry sessions (issue #72), for authenticating GIT to your
- * Kanonak package repositories.
- *
- * Publisher-centric: every subcommand takes the PUBLISHER domain you connected
- * to (`paul.kanonak.com`), not the OAuth authority host it resolves to. The
- * mapping is the device enrollment captured by `connect`/`enroll`; see
- * `resolveEnrolledAuthority`.
- *
- * Scope: the CLI provides dynamic GIT authentication and does not manage
- * package-manager-native registry credentials. Kanonak packages live in Git, so
- * the git credential helper (plus Go's `GOAUTH=git` and any `git+https`
- * dependency fetch) is the universal mechanism; package-manager registry auth is
- * out of scope here.
- *
- * `install-git-helper` wires `kanonak` in as a git credential helper; pushes and
- * pulls then authenticate transparently (a fresh session minted from the cert per
- * request, the repo host resolved to its authority via RFC 9728). `token` hands
- * out a session token on demand for any other use (a git credential file, an env
- * var, CI).
- */
-export declare function sessionCommand(): Command;