@floegence/redevplugin-contracts 0.0.0-dev

package/dist/release-signing.d.ts

@@ -0,0 +1,434 @@
+export declare const rootDelegationSchemaVersion: "redevplugin.release_root_delegation.v1";
+export declare const packageSignatureSchemaVersion: "redevplugin.package_signature.v1";
+export declare const releaseMetadataSchemaVersion: "redevplugin.release_metadata.v5";
+export declare const sourcePolicySchemaVersion: "redevplugin.release_source_policy.v2";
+export declare const sourcePolicyPointerSchemaVersion: "redevplugin.release_source_policy_pointer.v1";
+export declare const revocationSchemaVersion: "redevplugin.release_revocation.v2";
+export declare const revocationPointerSchemaVersion: "redevplugin.release_revocation_pointer.v1";
+export declare const releaseSigningLedgerEvidenceSchemaVersion: "redevplugin.release_signing_ledger_evidence.v1";
+export declare const signingSubjectSchemaVersion: "redevplugin.release_signing_subject.v1";
+export declare const signatureEnvelopeSchemaVersion: "redevplugin.release_signature_envelope.v1";
+export declare const signingLedgerSchemaVersion: "redevplugin.release_signing_ledger.v1";
+export declare const signingLedgerEntrySchemaVersion: "redevplugin.release_signing_ledger_entry.v1";
+export declare const signingLedgerLogLeafSchemaVersion: "redevplugin.release_signing_ledger_log_leaf.v1";
+export declare const signingLedgerReceiptSchemaVersion: "redevplugin.release_signing_ledger_receipt.v1";
+export declare const signatureAlgorithmEd25519: "ed25519";
+export declare const genesisPreviousEpoch: "0";
+export declare const genesisPreviousDocumentSHA256: string;
+export declare const signingUsages: {
+    readonly rootDelegation: "redevplugin.release-signing.root-delegation.v1";
+    readonly package: "redevplugin.release-signing.package.v1";
+    readonly releaseMetadata: "redevplugin.release-signing.release-metadata.v1";
+    readonly sourcePolicy: "redevplugin.release-signing.source-policy-document.v1";
+    readonly sourcePolicyPointer: "redevplugin.release-signing.source-policy-pointer.v1";
+    readonly revocation: "redevplugin.release-signing.revocation-document.v1";
+    readonly revocationPointer: "redevplugin.release-signing.revocation-pointer.v1";
+};
+export type SigningUsage = (typeof signingUsages)[keyof typeof signingUsages];
+export type DelegatedKeyUsage = "package" | "release_metadata" | "host_capability_contract" | "source_policy_document" | "source_policy_pointer" | "revocation_document" | "revocation_pointer" | "signing_ledger" | "trusted_time";
+export type RootDelegatedKey = Readonly<{
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    public_key: string;
+    usages: readonly DelegatedKeyUsage[];
+    channels: readonly string[];
+    valid_from: string;
+    valid_until: string;
+}>;
+export type RootDelegationV1 = Readonly<{
+    schema_version: typeof rootDelegationSchemaVersion;
+    source_id: string;
+    root_epoch: string;
+    previous_root_epoch: string;
+    previous_delegation_sha256: string;
+    generated_at: string;
+    expires_at: string;
+    delegated_keys: readonly RootDelegatedKey[];
+    key_id: string;
+    signature: string;
+}>;
+export type RootDelegationInput = Omit<RootDelegationV1, "schema_version" | "signature">;
+export type PackageSigningInput = Readonly<{
+    source_id: string;
+    channel: string;
+    version: string;
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    publisher_id: string;
+    plugin_id: string;
+    package_hash: string;
+    manifest_hash: string;
+    entries_hash: string;
+    signed_at: string;
+}>;
+export type PackageVerificationContext = Readonly<{
+    source_id: string;
+    channel: string;
+    version: string;
+}>;
+export type PackageSignatureV1 = Readonly<{
+    schema_version: typeof packageSignatureSchemaVersion;
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    publisher_id?: string;
+    plugin_id?: string;
+    package_hash: string;
+    manifest_hash: string;
+    entries_hash: string;
+    signature: string;
+    signed_at?: string;
+}>;
+export type ReleaseDistributionRef = Readonly<{
+    distribution: "registry_ref" | "host_artifact_ref";
+    artifact_ref: string;
+}>;
+export type ReleasePackageHashSet = Readonly<{
+    package_sha256: string;
+    manifest_sha256: string;
+    entries_sha256: string;
+}>;
+export type ReleaseMetadataSignatureRef = Readonly<{
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    signature_ref: string;
+    source_policy_epoch: string;
+    revocation_epoch: string;
+}>;
+export type PackageReleaseSignatureRef = Readonly<{
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    signature_bundle_ref: string;
+    source_policy_epoch: string;
+    revocation_epoch: string;
+}>;
+export type ReleaseCompatibility = Readonly<{
+    min_redevplugin_version: string;
+    min_runtime_version: string;
+    ui_protocol_version: "plugin-ui-v5";
+    supported_targets?: readonly ("darwin/amd64" | "darwin/arm64" | "linux/amd64" | "linux/arm64")[];
+}>;
+export type HostCapabilityContractRef = Readonly<{
+    publisher_id: string;
+    contract_id: string;
+    contract_version: string;
+    artifact_ref: string;
+    artifact_sha256: string;
+    manifest_ref: string;
+    manifest_sha256: string;
+    signature_ref: string;
+    signature_sha256: string;
+    signature_key_id: string;
+    signature_policy_epoch: string;
+    signature_revocation_epoch: string;
+    compatibility_ref: string;
+    compatibility_sha256: string;
+    generated_client_ref: string;
+    generated_client_sha256: string;
+    notices_ref: string;
+    notices_sha256: string;
+}>;
+export type HostCapabilityRequirementRef = Readonly<{
+    capability_id: string;
+    capability_version: string;
+    contract: HostCapabilityContractRef;
+}>;
+export type ReleaseHostRequirement = Readonly<{
+    host_id: string;
+    min_host_version?: string;
+    required_capability_contracts?: readonly HostCapabilityRequirementRef[];
+}>;
+export type ReleaseEvidence = Readonly<{
+    notices_sha256?: string;
+    provenance_sha256?: string;
+    generated_at?: string;
+}>;
+export type ReleaseMetadataV5 = Readonly<{
+    schema_version: typeof releaseMetadataSchemaVersion;
+    source_id: string;
+    release_metadata_ref: string;
+    publisher_id: string;
+    plugin_id: string;
+    version: string;
+    distribution_ref: ReleaseDistributionRef;
+    hashes: ReleasePackageHashSet;
+    release_metadata_signature: ReleaseMetadataSignatureRef;
+    package_signature: PackageReleaseSignatureRef;
+    compatibility: ReleaseCompatibility;
+    host_requirements?: readonly ReleaseHostRequirement[];
+    release_evidence?: ReleaseEvidence;
+    metadata?: Readonly<Record<string, string>>;
+}>;
+export type SourcePolicyLimits = Readonly<{
+    document_max_lifetime_seconds: 86400;
+    future_skew_seconds: 300;
+    activation_lease_max_seconds: 300;
+    refresh_interval_max_seconds: 60;
+    failure_teardown_deadline_seconds: 30;
+}>;
+export declare const defaultSourcePolicyLimits: SourcePolicyLimits;
+export type SourcePolicyActiveKeys = Readonly<{
+    package: readonly string[];
+    release_metadata: readonly string[];
+    host_capability_contract: readonly string[];
+    source_policy_pointer: readonly string[];
+    revocation_document: readonly string[];
+    revocation_pointer: readonly string[];
+}>;
+export type SourcePolicyCapabilityPublisherScope = Readonly<{
+    key_id: string;
+    allowed_publishers: readonly string[];
+}>;
+export type SourcePolicyV2 = Readonly<{
+    schema_version: typeof sourcePolicySchemaVersion;
+    source_id: string;
+    channel: string;
+    epoch: string;
+    previous_epoch: string;
+    previous_document_sha256: string;
+    root_epoch: string;
+    source_type: "registry" | "host_artifact";
+    source_class: "official" | "curated" | "community" | "private";
+    allowed_publishers: readonly string[];
+    allowed_artifact_hosts: readonly string[];
+    active_keys: SourcePolicyActiveKeys;
+    capability_publisher_scopes: readonly SourcePolicyCapabilityPublisherScope[];
+    require_signature: boolean;
+    install_policy: "allow" | "review_required" | "block";
+    unsigned_policy: "dev_only" | "review_required" | "block";
+    downgrade_policy: "review_required" | "block";
+    minimum_revocation_epoch: string;
+    limits: SourcePolicyLimits;
+    generated_at: string;
+    expires_at: string;
+    key_id: string;
+    signature: string;
+}>;
+export type SourcePolicyInput = Omit<SourcePolicyV2, "schema_version" | "signature">;
+export type ReleasePointerInput = Readonly<{
+    source_id: string;
+    channel: string;
+    epoch: string;
+    previous_epoch: string;
+    previous_document_sha256: string;
+    ref: string;
+    document_sha256: string;
+    generated_at: string;
+    expires_at: string;
+    key_id: string;
+}>;
+export type SourcePolicyPointerV1 = Readonly<ReleasePointerInput & {
+    schema_version: typeof sourcePolicyPointerSchemaVersion;
+    signature: string;
+}>;
+export type RevokedRelease = Readonly<{
+    publisher_id: string;
+    plugin_id: string;
+    version: string;
+    release_metadata_sha256: string;
+    revoked_at: string;
+}>;
+export type RevocationV2 = Readonly<{
+    schema_version: typeof revocationSchemaVersion;
+    source_id: string;
+    channel: string;
+    epoch: string;
+    previous_epoch: string;
+    previous_document_sha256: string;
+    root_epoch: string;
+    generated_at: string;
+    expires_at: string;
+    revoked_key_ids: readonly string[];
+    revoked_releases: readonly RevokedRelease[];
+    key_id: string;
+    signature: string;
+}>;
+export type RevocationInput = Omit<RevocationV2, "schema_version" | "signature">;
+export type RevocationPointerV1 = Readonly<ReleasePointerInput & {
+    schema_version: typeof revocationPointerSchemaVersion;
+    signature: string;
+}>;
+export type SigningLedgerEvidenceV1 = Readonly<{
+    schema_version: typeof releaseSigningLedgerEvidenceSchemaVersion;
+    source_id: string;
+    channel?: string;
+    subject_identity_sha256: string;
+    signing_preimage_sha256: string;
+    signature_envelope_sha256: string;
+    receipt_ref: string;
+    receipt_sha256: string;
+    checkpoint_ref: string;
+    checkpoint_sha256: string;
+    inclusion_proof_ref: string;
+    inclusion_proof_sha256: string;
+    latest_proof_ref: string;
+    latest_proof_sha256: string;
+    consistency_proof_ref?: string;
+    consistency_proof_sha256?: string;
+}>;
+export type SigningSubjectUsage = "root_delegation" | "package" | "release_metadata" | "source_policy_document" | "source_policy_pointer" | "revocation_document" | "revocation_pointer";
+export type SigningSubjectV1 = Readonly<{
+    schema_version: typeof signingSubjectSchemaVersion;
+    usage: SigningSubjectUsage;
+    source_id: string;
+    channel?: string;
+    root_epoch?: string;
+    publisher_id?: string;
+    plugin_id?: string;
+    version?: string;
+    artifact_or_metadata_identity_sha256?: string;
+    epoch?: string;
+}>;
+export type SignatureEnvelopeV1 = Readonly<{
+    schema_version: typeof signatureEnvelopeSchemaVersion;
+    subject_identity_sha256: string;
+    signing_preimage_sha256: string;
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    signature: string;
+}>;
+export type SigningLedgerEntryState = "reserved" | "finalized" | "terminal_failed";
+export type SigningLedgerFailureCode = "signer_rejected" | "subject_conflict" | "ledger_rejected";
+export type SigningLedgerEntryV1 = Readonly<{
+    schema_version: typeof signingLedgerEntrySchemaVersion;
+    state: SigningLedgerEntryState;
+    subject: SigningSubjectV1;
+    subject_identity_sha256: string;
+    signing_preimage_sha256: string;
+    algorithm: typeof signatureAlgorithmEd25519;
+    key_id: string;
+    revision: number;
+    reserved_at: string;
+    signature_envelope?: SignatureEnvelopeV1;
+    signature_envelope_sha256?: string;
+    finalized_at?: string;
+    failure_code?: SigningLedgerFailureCode;
+    failed_at?: string;
+}>;
+export type SigningLedgerLogLeafV1 = Readonly<{
+    schema_version: typeof signingLedgerLogLeafSchemaVersion;
+    source_id: string;
+    channel?: string;
+    subject_identity_sha256: string;
+    signing_preimage_sha256: string;
+    signature_envelope_sha256: string;
+    sequence: number;
+}>;
+export type SigningLedgerCheckpointV1 = Readonly<{
+    schema_version: typeof signingLedgerSchemaVersion;
+    kind: "checkpoint";
+    log_id: string;
+    tree_size: number;
+    log_root_hash: string;
+    latest_map_root_hash: string;
+    checkpoint_time: string;
+    key_id: string;
+    signature: string;
+}>;
+export type SigningLedgerReceiptV1 = Readonly<{
+    schema_version: typeof signingLedgerReceiptSchemaVersion;
+    log_id: string;
+    source_id: string;
+    channel?: string;
+    subject_identity_sha256: string;
+    signing_preimage_sha256: string;
+    signature_envelope_sha256: string;
+    sequence: number;
+    leaf_index: number;
+    tree_size: number;
+    log_root_hash: string;
+    latest_map_root_hash: string;
+    checkpoint_sha256: string;
+    checkpoint_time: string;
+    key_id: string;
+    signature: string;
+}>;
+export type SigningLedgerInclusionProofV1 = Readonly<{
+    schema_version: typeof signingLedgerSchemaVersion;
+    kind: "inclusion_proof";
+    log_id: string;
+    leaf_index: number;
+    tree_size: number;
+    nodes: readonly string[];
+}>;
+export type SigningLedgerLatestProofV1 = Readonly<{
+    schema_version: typeof signingLedgerSchemaVersion;
+    kind: "latest_proof";
+    log_id: string;
+    subject_identity_sha256: string;
+    present: boolean;
+    sequence?: number;
+    signing_preimage_sha256?: string;
+    signature_envelope_sha256?: string;
+    siblings: readonly string[];
+}>;
+export type SigningLedgerConsistencyProofV1 = Readonly<{
+    schema_version: typeof signingLedgerSchemaVersion;
+    kind: "consistency_proof";
+    log_id: string;
+    old_tree_size: number;
+    new_tree_size: number;
+    nodes: readonly string[];
+}>;
+export type SignatureVerificationRequest = Readonly<{
+    usage: SigningUsage;
+    keyID: string;
+    signingPreimageSHA256: Uint8Array;
+    signature: Uint8Array;
+}>;
+export type SignatureVerifier = (request: SignatureVerificationRequest) => boolean | Promise<boolean>;
+export declare class InvalidReleaseDocumentError extends TypeError {
+    constructor();
+}
+export declare class InvalidReleaseSignatureError extends Error {
+    constructor();
+}
+export declare function buildRootDelegation(input: RootDelegationInput, signature: Uint8Array): RootDelegationV1;
+export declare function rootDelegationSigningPreimage(input: RootDelegationInput): Uint8Array;
+export declare function canonicalRootDelegation(document: RootDelegationV1): Uint8Array;
+export declare function verifyRootDelegation(document: RootDelegationV1, verifier: SignatureVerifier): Promise<void>;
+export declare function buildPackageSignature(input: PackageSigningInput, signature: Uint8Array): PackageSignatureV1;
+export declare function packageSigningPreimage(input: PackageSigningInput): Uint8Array;
+export declare function canonicalPackageSignature(context: PackageVerificationContext, document: PackageSignatureV1): Uint8Array;
+export declare function verifyPackageSignature(context: PackageVerificationContext, document: PackageSignatureV1, verifier: SignatureVerifier): Promise<void>;
+export declare function buildReleaseMetadata(document: ReleaseMetadataV5): ReleaseMetadataV5;
+export declare function releaseMetadataSigningPreimage(channel: string, document: ReleaseMetadataV5): Uint8Array;
+export declare function canonicalReleaseMetadata(document: ReleaseMetadataV5): Uint8Array;
+export declare function verifyReleaseMetadata(channel: string, document: ReleaseMetadataV5, signature: Uint8Array, verifier: SignatureVerifier): Promise<void>;
+export declare function buildSourcePolicy(input: SourcePolicyInput, signature: Uint8Array): SourcePolicyV2;
+export declare function sourcePolicySigningPreimage(input: SourcePolicyInput): Uint8Array;
+export declare function canonicalSourcePolicy(document: SourcePolicyV2): Uint8Array;
+export declare function verifySourcePolicy(document: SourcePolicyV2, verifier: SignatureVerifier): Promise<void>;
+export declare function buildSourcePolicyPointer(input: ReleasePointerInput, signature: Uint8Array): SourcePolicyPointerV1;
+export declare function sourcePolicyPointerSigningPreimage(input: ReleasePointerInput): Uint8Array;
+export declare function canonicalSourcePolicyPointer(document: SourcePolicyPointerV1): Uint8Array;
+export declare function verifySourcePolicyPointer(document: SourcePolicyPointerV1, verifier: SignatureVerifier): Promise<void>;
+export declare function buildRevocation(input: RevocationInput, signature: Uint8Array): RevocationV2;
+export declare function revocationSigningPreimage(input: RevocationInput): Uint8Array;
+export declare function canonicalRevocation(document: RevocationV2): Uint8Array;
+export declare function verifyRevocation(document: RevocationV2, verifier: SignatureVerifier): Promise<void>;
+export declare function buildRevocationPointer(input: ReleasePointerInput, signature: Uint8Array): RevocationPointerV1;
+export declare function revocationPointerSigningPreimage(input: ReleasePointerInput): Uint8Array;
+export declare function canonicalRevocationPointer(document: RevocationPointerV1): Uint8Array;
+export declare function verifyRevocationPointer(document: RevocationPointerV1, verifier: SignatureVerifier): Promise<void>;
+export declare function decodeRootDelegation(raw: Uint8Array | string): RootDelegationV1;
+export declare function decodePackageSignature(raw: Uint8Array | string, context: PackageVerificationContext): PackageSignatureV1;
+export declare function decodeReleaseMetadata(raw: Uint8Array | string): ReleaseMetadataV5;
+export declare function decodeSourcePolicy(raw: Uint8Array | string): SourcePolicyV2;
+export declare function decodeSourcePolicyPointer(raw: Uint8Array | string): SourcePolicyPointerV1;
+export declare function decodeRevocation(raw: Uint8Array | string): RevocationV2;
+export declare function decodeRevocationPointer(raw: Uint8Array | string): RevocationPointerV1;
+export declare function decodeSigningLedgerEvidence(raw: Uint8Array | string): SigningLedgerEvidenceV1;
+export declare function canonicalSigningSubject(value: SigningSubjectV1): Uint8Array;
+export declare function decodeSigningSubject(raw: Uint8Array | string): SigningSubjectV1;
+export declare function canonicalSignatureEnvelope(value: SignatureEnvelopeV1): Uint8Array;
+export declare function decodeSignatureEnvelope(raw: Uint8Array | string): SignatureEnvelopeV1;
+export declare function canonicalSigningLedgerEntry(value: SigningLedgerEntryV1): Uint8Array;
+export declare function decodeSigningLedgerEntry(raw: Uint8Array | string): SigningLedgerEntryV1;
+export declare function verifySigningLedgerEntryBindings(value: SigningLedgerEntryV1): Promise<void>;
+export declare function decodeSigningLedgerLogLeaf(raw: Uint8Array | string): SigningLedgerLogLeafV1;
+export declare function decodeSigningLedgerCheckpoint(raw: Uint8Array | string): SigningLedgerCheckpointV1;
+export declare function decodeSigningLedgerReceipt(raw: Uint8Array | string): SigningLedgerReceiptV1;
+export declare function decodeSigningLedgerInclusionProof(raw: Uint8Array | string): SigningLedgerInclusionProofV1;
+export declare function decodeSigningLedgerLatestProof(raw: Uint8Array | string): SigningLedgerLatestProofV1;
+export declare function decodeSigningLedgerConsistencyProof(raw: Uint8Array | string): SigningLedgerConsistencyProofV1;
+export declare function createEd25519Verifier(publicKeys: Readonly<Record<string, Uint8Array>>, subtle?: SubtleCrypto): SignatureVerifier;