@kanonak-protocol/types 1.1.0

package/dist/registry/models/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Kanonak CLI configuration loaded from system and user config files     Supports registry overrides, discovery settings, and enterprise deployments
+ */
+export interface KanonakConfiguration {
+    /**
+     * Registry overrides by domain pattern (supports wildcards)
+     */
+    registryOverrides: Record<string, RegistryOverride>;
+    /**
+     * Discovery service settings
+     */
+    discovery: DiscoverySettings;
+    /**
+     * Find registry override for a given domain     Supports exact match and wildcard patterns (*.acme.internal)
+     */
+    getOverride(domain: string): RegistryOverride | null;
+    /**
+     * Merge another configuration into this one     Used to combine system and user configs (user overrides system)
+     */
+    merge(other: KanonakConfiguration): void;
+}
+/**
+ * Represents a single locked package entry
+ */
+export interface KanonakLockEntry {
+    /**
+     * The resolved version (e.g., "1.0.0")
+     */
+    version: string;
+    /**
+     * The full OCI reference where this package was resolved from     (e.g., "ghcr.io/kanonak-protocol-org/core-rdf:1.0.1")
+     */
+    resolved: string;
+    /**
+     * Content integrity hash (SHA256 digest from OCI manifest)     Format: "sha256:abc123..."
+     */
+    integrity: string;
+    /**
+     * Direct dependencies of this package (namespace → version)     e.g., {"kanonak.org/core-rdfs": "1.0.1", "kanonak.org/core-owl": "1.0.1"}
+     */
+    dependencies?: Record<string, string> | undefined;
+    /**
+     * Timestamp when this package was installed
+     */
+    installedAt?: unknown | null | undefined;
+}
+/**
+ * Represents the kanonak.lock file that locks package versions for reproducible builds.     Similar to package-lock.json (npm) or Cargo.lock (Rust).
+ */
+export interface KanonakLockFile {
+    /**
+     * Lock file format version (currently "1")
+     */
+    version: string;
+    /**
+     * Map of package references to resolved package information     Key format: "publisher/package" (e.g., "kanonak.org/core-rdf")
+     */
+    packages: Record<string, KanonakLockEntry>;
+    /**
+     * Timestamp when this lock file was last updated
+     */
+    lastUpdated?: unknown | null | undefined;
+}
+/**
+ * Represents a package reference that can be resolved from an OCI registry.     Supports multiple formats:     - Short form: "kanonak.org/core-rdf" or "kanonak.org/core-rdf@1.0.1"     - Full OCI reference: "ghcr.io/kanonak-protocol-org/core-rdf:1.0.1"
+ */
+export interface KanonakPackageReference {
+    /**
+     * The registry hostname (e.g., "ghcr.io", "docker.io", "harbor.company.internal")     If null, the default registry from configuration will be used.
+     */
+    registry?: string | null | undefined;
+    /**
+     * The publisher/organization (e.g., "kanonak-protocol", "stories")
+     */
+    publisher: string;
+    /**
+     * The package name (e.g., "rdf", "trading")
+     */
+    package_: string;
+    /**
+     * The version or tag (e.g., "1.0.0", "latest")     If null, will resolve to latest or use version from lock file.
+     */
+    version?: string | null | undefined;
+    /**
+     * The original reference string as provided by the user
+     */
+    originalReference: string;
+    /**
+     * Convert to OCI reference format (registry/publisher/package:version)
+     */
+    toOciReference(defaultRegistry?: string): string;
+    /**
+     * Convert to Kanonak import format (publisher/package@version)
+     */
+    toKanonakImport(): string;
+    /**
+     * Get the file path for this package in the .kanonak/ directory     Format: .kanonak/publisher/package@version.kan.yml
+     */
+    getLocalFilePath(workspaceRoot: string): string;
+    toString(): string;
+}
+/**
+ * Configuration for Kanonak registry settings (.kanonakrc or kanonak.json).     Allows users to customize registry behavior, auth, mirrors, etc.
+ */
+export interface KanonakRegistryConfig {
+    /**
+     * Registry configuration options
+     */
+    registries: RegistryConfiguration;
+}
+/**
+ * Configuration for a custom/private registry
+ */
+export interface CustomRegistryConfig {
+    /**
+     * The full URL of the registry     (e.g., "https://harbor.company.internal")
+     */
+    url?: string | null | undefined;
+    /**
+     * Authentication method:     - "docker-config" - use ~/.docker/config.json     - "azure-cli" - use Azure CLI for ACR     - "aws-cli" - use AWS CLI for ECR     - "gcloud-cli" - use Google Cloud CLI for GAR     - "github-token" - use GITHUB_TOKEN environment variable     - "env" - use environment variables (KANONAK_USERNAME, KANONAK_PASSWORD)     - "token" - use static token from config
+     */
+    auth: string;
+    /**
+     * Static token (only used if Auth = "token")     Not recommended for sensitive credentials - use credential helpers instead
+     */
+    token?: string | null | undefined;
+    /**
+     * Whether to use HTTPS (default: true)
+     */
+    useHttps: boolean;
+    /**
+     * Whether to skip TLS verification (insecure, for development only)
+     */
+    skipTlsVerify: boolean;
+}
+/**
+ * Discovery service settings
+ */
+export interface DiscoverySettings {
+    /**
+     * Enable/disable .well-known discovery globally     Set to false for air-gapped environments
+     */
+    enabled?: boolean | null | undefined;
+    /**
+     * Timeout for .well-known fetches in seconds
+     */
+    timeout?: number | null | undefined;
+}
+/**
+ * Configuration for publishing packages
+ */
+export interface PublishingConfiguration {
+    /**
+     * Default registry to publish to (e.g., "ghcr.io")
+     */
+    registry?: string | null | undefined;
+    /**
+     * Default namespace/publisher (e.g., "my-org")
+     */
+    namespace_?: string | null | undefined;
+}
+export interface RegistryConfiguration {
+    /**
+     * Default registry to use for package resolution     (e.g., "ghcr.io", "docker.io", "harbor.company.internal")
+     */
+    default_: string;
+    /**
+     * List of mirror registries to try if default fails     (e.g., ["ghcr.io", "docker.io"])
+     */
+    mirrors: Array<string>;
+    /**
+     * Custom registry configurations by hostname     Allows specifying auth methods and URLs for private registries
+     */
+    custom: Record<string, CustomRegistryConfig>;
+    /**
+     * Publishing configuration (where to publish packages)
+     */
+    publishing?: PublishingConfiguration | null | undefined;
+}
+/**
+ * Represents registry discovery metadata from .well-known/kanonak-registry.kan.yml     Enables domain-based publishers to specify where their packages are hosted
+ */
+export interface RegistryMetadata {
+    /**
+     * Discovery protocol version (currently "1")
+     */
+    version: string;
+    /**
+     * OCI registry hostname (e.g., "ghcr.io", "harbor.company.com:5000")
+     */
+    registry: string;
+    /**
+     * Namespace/account on the registry (can contain slashes for nested paths, or be empty)     Examples:     - "username" (GitHub, Docker Hub)     - "project/repo" (Google Artifact Registry)     - "" (Azure ACR, AWS ECR with account in hostname)
+     */
+    namespace_: string;
+    /**
+     * URI scheme for registry connection (default: "https")     Set to "http" for insecure private registries
+     */
+    scheme: string;
+    /**
+     * Cache time-to-live in seconds (default: 3600 = 1 hour)
+     */
+    ttl: number;
+    /**
+     * Optional human-readable description
+     */
+    description?: string | null | undefined;
+    /**
+     * Optional contact URL (e.g., contact form, GitHub issues, support page)
+     */
+    contactUrl?: string | null | undefined;
+    /**
+     * Timestamp when this metadata was cached
+     */
+    cachedAt: unknown;
+    /**
+     * Construct OCI reference from discovered metadata
+     */
+    toOciReference(package_: string, version: string): string;
+    /**
+     * Check if cached metadata is still valid based on TTL
+     */
+    isExpired(): boolean;
+}
+/**
+ * Registry override configuration for a domain pattern
+ */
+export interface RegistryOverride {
+    /**
+     * OCI registry hostname (e.g., "harbor.acme.com")
+     */
+    registry: string;
+    /**
+     * Namespace on the registry (can contain slashes or be empty)
+     */
+    namespace_: string;
+    /**
+     * Skip .well-known discovery and use this override directly     If false, tries .well-known first, falls back to this override
+     */
+    skipDiscovery: boolean;
+    /**
+     * Optional URI scheme (default: https)
+     */
+    scheme: string;
+    /**
+     * Optional TTL override for cached metadata
+     */
+    ttl?: number | null | undefined;
+    /**
+     * Convert to RegistryMetadata for use by discovery service
+     */
+    toMetadata(): RegistryMetadata;
+}

package/dist/registry/oauth/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * OAuth callback result.
+ */
+export interface CallbackResult {
+    code?: string | null | undefined;
+    state?: string | null | undefined;
+    error?: string | null | undefined;
+}
+/**
+ * Dynamic client registration response (RFC 7591).
+ */
+export interface ClientRegistration {
+    clientId?: string | null | undefined;
+    clientSecret?: string | null | undefined;
+    clientIdIssuedAt?: number | null | undefined;
+    clientSecretExpiresAt?: number | null | undefined;
+}
+/**
+ * Local HTTP server for OAuth callback.
+ */
+export interface LocalCallbackServer {
+    startAsync(ct: AbortSignal): Promise<[string, number]>;
+    waitForCallbackAsync(ct: AbortSignal): Promise<CallbackResult | null>;
+    dispose(): void;
+}
+/**
+ * Stores OAuth credentials per domain in ~/.kanonak/credentials.json.     Vendor-agnostic - works with any OAuth-enabled Git registry.
+ */
+export interface OAuthCredentialStore {
+    /**
+     * Get stored credentials for a host.
+     */
+    getAsync(host: string, ct?: AbortSignal): Promise<StoredCredential | null>;
+    /**
+     * Store credentials for a host.
+     */
+    storeAsync(host: string, credential: StoredCredential, ct?: AbortSignal): Promise<void>;
+    /**
+     * Remove credentials for a host.
+     */
+    removeAsync(host: string, ct?: AbortSignal): Promise<void>;
+    /**
+     * List all hosts with stored credentials.
+     */
+    listHostsAsync(ct?: AbortSignal): Promise<readonly string[]>;
+    /**
+     * Check if credentials exist and are valid for a host.
+     */
+    hasValidCredentialAsync(host: string, ct?: AbortSignal): Promise<boolean>;
+}
+/**
+ * Discovers OAuth server metadata using RFC 8414.     Vendor-agnostic - works with any OAuth 2.0 compliant server.
+ */
+export interface OAuthDiscoveryService {
+    /**
+     * Discover OAuth server metadata for a host.     Tries RFC 8414 .well-known/oauth-authorization-server first.
+     */
+    discoverAsync(host: string, ct?: AbortSignal): Promise<OAuthServerMetadata | null>;
+    /**
+     * Check if a host supports OAuth discovery.
+     */
+    supportsOAuthAsync(host: string, ct?: AbortSignal): Promise<boolean>;
+}
+/**
+ * OAuth 2.0 Authorization Code Flow with PKCE.     Supports dynamic client registration (RFC 7591).     Vendor-agnostic - works with any OAuth 2.0 compliant server.
+ */
+export interface OAuthFlowService {
+    /**
+     * Perform the full OAuth authorization flow for a host.     1. Discover OAuth endpoints     2. Register client dynamically (if supported)     3. Open browser for authorization     4. Receive callback with authorization code     5. Exchange code for tokens     6. Store credentials
+     */
+    authorizeAsync(host: string, scopes: Array<string>, ct?: AbortSignal): Promise<OAuthResult>;
+    /**
+     * Refresh an expired access token.
+     */
+    refreshTokenAsync(host: string, ct?: AbortSignal): Promise<OAuthResult>;
+    /**
+     * Revoke tokens and remove credentials for a host.
+     */
+    logoutAsync(host: string, ct?: AbortSignal): Promise<OAuthResult>;
+}
+/**
+ * Result of an OAuth operation.
+ */
+export interface OAuthResult {
+    isSuccess: boolean;
+    host?: string | null | undefined;
+    errorMessage?: string | null | undefined;
+}
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414).
+ */
+export interface OAuthServerMetadata {
+    /**
+     * Authorization server's issuer identifier.
+     */
+    issuer?: string | null | undefined;
+    /**
+     * URL of the authorization endpoint.
+     */
+    authorizationEndpoint?: string | null | undefined;
+    /**
+     * URL of the token endpoint.
+     */
+    tokenEndpoint?: string | null | undefined;
+    /**
+     * URL of the dynamic client registration endpoint (RFC 7591).
+     */
+    registrationEndpoint?: string | null | undefined;
+    /**
+     * URL of the token revocation endpoint (RFC 7009).
+     */
+    revocationEndpoint?: string | null | undefined;
+    /**
+     * JSON array of supported scopes.
+     */
+    scopesSupported?: Array<string> | null | undefined;
+    /**
+     * JSON array of supported response types.
+     */
+    responseTypesSupported?: Array<string> | null | undefined;
+    /**
+     * JSON array of supported grant types.
+     */
+    grantTypesSupported?: Array<string> | null | undefined;
+    /**
+     * JSON array of supported PKCE code challenge methods.
+     */
+    codeChallengeMethodsSupported?: Array<string> | null | undefined;
+    /**
+     * JSON array of supported token endpoint auth methods.
+     */
+    tokenEndpointAuthMethodsSupported?: Array<string> | null | undefined;
+    /**
+     * Check if PKCE with S256 is supported.
+     */
+    readonly supportsPkceS256: boolean;
+    /**
+     * Check if dynamic client registration is supported.
+     */
+    readonly supportsDynamicRegistration: boolean;
+    /**
+     * Check if authorization code flow is supported.
+     */
+    readonly supportsAuthorizationCode: boolean;
+}
+/**
+ * OAuth credential stored per host.
+ */
+export interface StoredCredential {
+    /**
+     * OAuth client ID (from dynamic registration or pre-configured).
+     */
+    clientId?: string | null | undefined;
+    /**
+     * OAuth client secret (optional, for confidential clients).
+     */
+    clientSecret?: string | null | undefined;
+    /**
+     * OAuth access token for API calls.
+     */
+    accessToken?: string | null | undefined;
+    /**
+     * OAuth refresh token for obtaining new access tokens.
+     */
+    refreshToken?: string | null | undefined;
+    /**
+     * When the access token expires.
+     */
+    expiresAt?: unknown | null | undefined;
+    /**
+     * OAuth server metadata (cached for refresh).
+     */
+    tokenEndpoint?: string | null | undefined;
+    /**
+     * Check if the access token is expired (with 5 minute buffer).
+     */
+    readonly isExpired: boolean;
+    /**
+     * Check if the credential has a valid access token.
+     */
+    readonly hasValidToken: boolean;
+}
+/**
+ * OAuth token response.
+ */
+export interface TokenResponse {
+    accessToken?: string | null | undefined;
+    tokenType?: string | null | undefined;
+    expiresIn?: number | null | undefined;
+    refreshToken?: string | null | undefined;
+    scope?: string | null | undefined;
+}

package/dist/registry/providers/enums.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registry operations
+ */
+export declare enum RegistryOperation {
+    Install = 0,
+    Publish = 1,
+    Delete = 2
+}

package/dist/registry/providers/enums.js

@@ -0,0 +1 @@
+var u=(l=>(l[l.Install=0]="Install",l[l.Publish=1]="Publish",l[l.Delete=2]="Delete",l))(u||{});export{u as RegistryOperation};

package/dist/registry/providers/git/types.d.ts

@@ -0,0 +1,43 @@
+import { IRegistryProvider } from '../../../registry/providers/index';
+import { IKanonakRegistryService } from '../../../registry/services/index';
+/**
+ * Git credential (username + password/token).
+ */
+export interface GitCredential {
+    readonly username: string;
+    readonly password: string;
+}
+/**
+ * Generic credential provider for Git registries.     Supports OAuth tokens, environment variables, and git credential helpers.     Vendor-agnostic - no hardcoded registry names.
+ */
+export interface GitCredentialProvider {
+    /**
+     * Get credentials for a Git host.     Tries multiple sources in order: OAuth store, environment, git credential helper.
+     */
+    getCredentialAsync(gitHost: string, ct?: AbortSignal): Promise<GitCredential | null>;
+    /**
+     * Check if credentials exist for a host.
+     */
+    hasCredentialAsync(gitHost: string, ct?: AbortSignal): Promise<boolean>;
+}
+export interface GitPackageReference {
+    registry: string;
+    publisher: string;
+    package_: string;
+    version?: string | null | undefined;
+}
+/**
+ * Git-based registry provider.     Uses Git Smart HTTP protocol to clone/fetch Kanonak packages.     Vendor-agnostic - works with any Git registry supporting Smart HTTP.
+ */
+export interface GitRegistryProvider extends IRegistryProvider {
+    readonly name: string;
+    /**
+     * Set the registry service for transitive dependency installation.
+     */
+    setRegistryService(registryService: IKanonakRegistryService): void;
+    supportsRegistry(registryUrl: string): boolean;
+    installPackageAsync(packageRef: string, publisherDomain: string, workspaceRoot: string): Promise<string>;
+    publishPackageAsync(filePath: string, registry: string, publisher?: string | null): Promise<void>;
+    deletePackageVersionAsync(publisher: string, package_: string, version: string, registry: string): Promise<void>;
+    deleteEntirePackageAsync(publisher: string, package_: string, registry: string): Promise<void>;
+}

package/dist/registry/providers/github/models/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Container metadata including tags
+ */
+export interface GitHubContainerMetadata {
+    /**
+     * List of tags associated with this version
+     */
+    tags?: Array<string> | undefined;
+}
+/**
+ * Metadata for a GitHub package version
+ */
+export interface GitHubPackageMetadata {
+    /**
+     * Container-specific metadata
+     */
+    container?: GitHubContainerMetadata | null | undefined;
+}
+/**
+ * Represents a package version in GitHub Container Registry
+ */
+export interface GitHubPackageVersion {
+    /**
+     * Numeric ID used for deletion operations
+     */
+    id: number;
+    /**
+     * Version name (usually the digest)
+     */
+    name: string;
+    /**
+     * Package metadata including tags
+     */
+    metadata?: GitHubPackageMetadata | null | undefined;
+}

package/dist/registry/providers/github/types.d.ts

@@ -0,0 +1,30 @@
+import { GitHubPackageVersion } from '../../../registry/providers/github/models/types';
+import { IRegistryProvider } from '../../../registry/providers/index';
+/**
+ * HTTP client for GitHub Container Registry API operations
+ */
+export interface GitHubApiClient {
+    /**
+     * Get all versions of a package
+     */
+    getPackageVersionsAsync(owner: string, packageName: string): Promise<Array<GitHubPackageVersion>>;
+    /**
+     * Delete a specific package version by ID
+     */
+    deletePackageVersionAsync(owner: string, packageName: string, versionId: number): Promise<void>;
+    /**
+     * Delete an entire package (all versions)
+     */
+    deleteEntirePackageAsync(owner: string, packageName: string): Promise<void>;
+}
+/**
+ * GitHub Container Registry (ghcr.io) provider using GitHub REST API     for operations not supported by OCI spec (like deletions)
+ */
+export interface GitHubRegistryProvider extends IRegistryProvider {
+    readonly name: string;
+    supportsRegistry(registryUrl: string): boolean;
+    installPackageAsync(packageRef: string, publisherDomain: string, workspaceRoot: string): Promise<string>;
+    publishPackageAsync(filePath: string, registry: string, publisher?: string | null): Promise<void>;
+    deletePackageVersionAsync(publisher: string, package_: string, version: string, registry: string): Promise<void>;
+    deleteEntirePackageAsync(publisher: string, package_: string, registry: string): Promise<void>;
+}

package/dist/registry/providers/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Interface for registry-specific operations.     Implementations handle provider-specific logic (GitHub, Azure, Docker Hub, etc.)
+ */
+export interface IRegistryProvider {
+    /**
+     * Provider name for logging/debugging
+     */
+    readonly name: string;
+    /**
+     * Check if this provider supports the given registry URL
+     */
+    supportsRegistry(registryUrl: string): boolean;
+    /**
+     * Install package from registry
+     */
+    installPackageAsync(packageRef: string, publisherDomain: string, workspaceRoot: string): Promise<string>;
+    /**
+     * Publish package to registry
+     */
+    publishPackageAsync(filePath: string, registry: string, publisher?: string | null): Promise<void>;
+    /**
+     * Delete a specific version of a package from registry
+     */
+    deletePackageVersionAsync(publisher: string, package_: string, version: string, registry: string): Promise<void>;
+    /**
+     * Delete entire package (all versions) from registry
+     */
+    deleteEntirePackageAsync(publisher: string, package_: string, registry: string): Promise<void>;
+}

package/dist/registry/providers/oci/types.d.ts

@@ -0,0 +1,17 @@
+import { IRegistryProvider } from '../../../registry/providers/index';
+import { IKanonakRegistryService } from '../../../registry/services/index';
+/**
+ * OCI registry provider using ORAS library.     Works with any OCI-compliant registry (Docker Hub, Azure ACR, Harbor, etc.)
+ */
+export interface OciRegistryProvider extends IRegistryProvider {
+    readonly name: string;
+    /**
+     * Set the registry service for transitive dependency installation.     This is a setter injection to avoid circular dependency during construction.
+     */
+    setRegistryService(registryService: IKanonakRegistryService): void;
+    supportsRegistry(registryUrl: string): boolean;
+    installPackageAsync(packageRef: string, publisherDomain: string, workspaceRoot: string): Promise<string>;
+    publishPackageAsync(filePath: string, registry: string, publisher?: string | null): Promise<void>;
+    deletePackageVersionAsync(publisher: string, package_: string, version: string, registry: string): Promise<void>;
+    deleteEntirePackageAsync(publisher: string, package_: string, registry: string): Promise<void>;
+}

package/dist/registry/providers/types.d.ts

@@ -0,0 +1,15 @@
+import { RegistryOperation } from '../../registry/providers/enums';
+import { IRegistryProvider } from '../../registry/providers/index';
+/**
+ * Factory for creating the appropriate registry provider based on registry URL.     Uses strategy pattern to select provider-specific implementations.
+ */
+export interface RegistryProviderFactory {
+    /**
+     * Get the appropriate provider for the given registry URL.     Returns the first provider that supports the registry,     or falls back to OCI provider for all other registries.
+     */
+    getProvider(registryUrl: string): IRegistryProvider;
+    /**
+     * Get a provider for a specific operation type.     Some providers only support certain operations (e.g., GitHub only supports delete).
+     */
+    getProviderForOperation(registryUrl: string, operation: RegistryOperation): IRegistryProvider;
+}

package/dist/registry/services/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface for package registry operations.     Enables dependency injection and prevents circular dependencies.
+ */
+export interface IKanonakRegistryService {
+    /**
+     * Install a package from a registry.     Downloads the package to .kanonak/ directory and updates kanonak.lock.     Uses domain-based discovery for all publishers (all publishers are domains).
+     */
+    installPackageAsync(packageRef: string, workspaceRoot: string): Promise<string>;
+}