@3sixty/immutable-proof-models 0.0.0-stage → 0.20.0-next.0

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

@@ -0,0 +1,47 @@
+import type { IComponent } from "@3sixty/core";
+import type { IJsonLdNodeObject } from "@3sixty/data-json-ld";
+import type { IImmutableProofCredential } from "./IImmutableProofCredential.js";
+import type { IImmutableProofVerification } from "./IImmutableProofVerification.js";
+/**
+ * Interface describing an immutable proof contract.
+ */
+export interface IImmutableProofComponent extends IComponent {
+    /**
+     * Create a new proof.
+     * @param document The document to create the proof for.
+     * @param options Optional settings for the proof.
+     * @param options.deleteLock An ISO 8601 date-time string specifying when the notarization lock expires; if omitted no lock is applied.
+     * @returns The id of the new proof.
+     */
+    create(document: IJsonLdNodeObject, options?: {
+        deleteLock?: string;
+    }): Promise<string>;
+    /**
+     * Get a proof.
+     * @param id The id of the proof to get.
+     * @returns The proof.
+     * @throws NotFoundError if the proof is not found.
+     */
+    get(id: string): Promise<IImmutableProofCredential>;
+    /**
+     * Verify a proof.
+     * @param id The id of the proof to verify.
+     * @returns The result of the verification and any failures.
+     * @throws NotFoundError if the proof is not found.
+     */
+    verify(id: string): Promise<IImmutableProofVerification>;
+    /**
+     * Remove the proof and its notarization.
+     * @param id The id of the proof to remove.
+     * @returns A promise that resolves when the proof and its notarization have been removed.
+     * @throws NotFoundError if the proof is not found.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Remove only the notarization for the proof, keeping the proof entity.
+     * @param id The id of the proof to remove the notarization from.
+     * @returns A promise that resolves when the notarization has been removed.
+     * @throws NotFoundError if the proof is not found.
+     */
+    removeNotarization(id: string): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+import type { IDidVerifiableCredential, IProof } from "@3sixty/standards-w3c-did";
+import type { IImmutableProofDataIntegrity } from "./IImmutableProofDataIntegrity.js";
+/**
+ * Interface describing an immutable proof credential.
+ */
+export interface IImmutableProofCredential extends Omit<IDidVerifiableCredential, "proof"> {
+    /**
+     * The proof of the verifiable credential, which includes the data integrity information.
+     */
+    proof?: IProof & IImmutableProofDataIntegrity;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Interface describing additional data integrity fields attached.
+ */
+export interface IImmutableProofDataIntegrity {
+    /**
+     * The notarization id.
+     * @json-ld id
+     */
+    notarizationId?: string;
+}

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

@@ -0,0 +1,26 @@
+import type { ImmutableProofContexts } from "./immutableProofContexts.js";
+import type { ImmutableProofFailure } from "./immutableProofFailure.js";
+import type { ImmutableProofTypes } from "./immutableProofTypes.js";
+/**
+ * Interface describing an immutable proof verification.
+ */
+export interface IImmutableProofVerification {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": typeof ImmutableProofContexts.Context;
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof ImmutableProofTypes.ImmutableProofVerification;
+    /**
+     * Was the verification successful.
+     * @json-ld namespace:twin-common
+     */
+    verified: boolean;
+    /**
+     * If the verification was unsuccessful the failure reason.
+     * @json-ld type:schema:Text
+     */
+    failure?: ImmutableProofFailure;
+}

package/dist/types/models/api/IImmutableProofCreateRequest.d.ts

@@ -0,0 +1,25 @@
+import type { IJsonLdNodeObject } from "@3sixty/data-json-ld";
+/**
+ * Create a proof.
+ */
+export interface IImmutableProofCreateRequest {
+    /**
+     * The parameters from the body.
+     */
+    body: {
+        /**
+         * The document to create the proof for.
+         */
+        document: IJsonLdNodeObject;
+        /**
+         * Optional settings for the proof.
+         */
+        options?: {
+            /**
+             * An ISO 8601 date-time string specifying when the notarization lock expires.
+             * If omitted, no deletion lock is applied.
+             */
+            deleteLock?: string;
+        };
+    };
+}

package/dist/types/models/api/IImmutableProofGetRequest.d.ts

@@ -0,0 +1,21 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+/**
+ * Get a proof.
+ */
+export interface IImmutableProofGetRequest {
+    /**
+     * The headers which can be used to determine the response data type.
+     */
+    headers?: {
+        [HeaderTypes.Accept]: typeof MimeTypes.Json | typeof MimeTypes.JsonLd;
+    };
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the immutable proof to get.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IImmutableProofGetResponse.d.ts

@@ -0,0 +1,17 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+import type { IImmutableProofCredential } from "../IImmutableProofCredential.js";
+/**
+ * Response to getting an immutable proof.
+ */
+export interface IImmutableProofGetResponse {
+    /**
+     * The headers which can be used to determine the response data type.
+     */
+    headers?: {
+        [HeaderTypes.ContentType]: typeof MimeTypes.Json | typeof MimeTypes.JsonLd;
+    };
+    /**
+     * The response body.
+     */
+    body: IImmutableProofCredential;
+}

package/dist/types/models/api/IImmutableProofRemoveNotarizationRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remove the notarization for a proof.
+ */
+export interface IImmutableProofRemoveNotarizationRequest {
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the immutable proof to remove the notarization from.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IImmutableProofRemoveRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remove a proof.
+ */
+export interface IImmutableProofRemoveRequest {
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the immutable proof to remove.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IImmutableProofVerifyRequest.d.ts

@@ -0,0 +1,21 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+/**
+ * Verify a proof.
+ */
+export interface IImmutableProofVerifyRequest {
+    /**
+     * The headers which can be used to determine the response data type.
+     */
+    headers?: {
+        [HeaderTypes.Accept]: typeof MimeTypes.Json | typeof MimeTypes.JsonLd;
+    };
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the immutable proof to verify.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/IImmutableProofVerifyResponse.d.ts

@@ -0,0 +1,17 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+import type { IImmutableProofVerification } from "../IImmutableProofVerification.js";
+/**
+ * Response to verifying an immutable proof.
+ */
+export interface IImmutableProofVerifyResponse {
+    /**
+     * The headers which can be used to determine the response data type.
+     */
+    headers?: {
+        [HeaderTypes.ContentType]: typeof MimeTypes.Json | typeof MimeTypes.JsonLd;
+    };
+    /**
+     * The response body.
+     */
+    body: IImmutableProofVerification;
+}

package/dist/types/models/eventBus/IImmutableProofEventBusProofCreated.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Event bus payload for proof created.
+ */
+export interface IImmutableProofEventBusProofCreated {
+    /**
+     * The id of the proof created.
+     */
+    id: string;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * The contexts of immutable proof data.
+ */
+export declare const ImmutableProofContexts: {
+    /**
+     * The canonical RDF namespace URI for Immutable Proof.
+     */
+    readonly Namespace: "https://schema.3sixty.global/immutable-proof/";
+    /**
+     * The value to use in context for Immutable Proof.
+     */
+    readonly Context: "https://schema.3sixty.global/immutable-proof/";
+    /**
+     * The JSON-LD Context URL for Immutable Proof.
+     */
+    readonly JsonLdContext: "https://schema.3sixty.global/immutable-proof/types.jsonld";
+    /**
+     * The canonical RDF namespace URI for TWIN Common.
+     */
+    readonly NamespaceCommon: "https://schema.3sixty.global/common/";
+    /**
+     * The value to use in JSON-LD context for TWIN Common.
+     */
+    readonly ContextCommon: "https://schema.3sixty.global/common/";
+    /**
+     * The JSON-LD Context URL for TWIN Common.
+     */
+    readonly JsonLdContextCommon: "https://schema.3sixty.global/common/types.jsonld";
+};
+/**
+ * The contexts of immutable proof data.
+ */
+export type ImmutableProofContexts = (typeof ImmutableProofContexts)[keyof typeof ImmutableProofContexts];

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

@@ -0,0 +1,25 @@
+/**
+ * The failure reason of the proof.
+ */
+export declare const ImmutableProofFailure: {
+    /**
+     * Proof not yet issued.
+     */
+    readonly NotIssued: "notIssued";
+    /**
+     * Proof missing.
+     */
+    readonly ProofMissing: "proofMissing";
+    /**
+     * Verification failure.
+     */
+    readonly VerificationFailure: "verificationFailure";
+    /**
+     * Revoked.
+     */
+    readonly Revoked: "revoked";
+};
+/**
+ * The failure reason of the proof.
+ */
+export type ImmutableProofFailure = (typeof ImmutableProofFailure)[keyof typeof ImmutableProofFailure];

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

@@ -0,0 +1,33 @@
+/**
+ * Metric IDs for the immutable proof service.
+ */
+export declare const ImmutableProofMetricIds: {
+    /**
+     * Number of proofs created.
+     */
+    readonly ProofsCreated: "ip_proofs_created";
+    /**
+     * Number of proof verifications succeeded.
+     */
+    readonly VerificationsSucceeded: "ip_verifications_succeeded";
+    /**
+     * Number of proof verifications failed.
+     */
+    readonly VerificationsFailed: "ip_verifications_failed";
+    /**
+     * Number of proofs removed.
+     */
+    readonly ProofsRemoved: "ip_proofs_removed";
+    /**
+     * Number of notarizations removed.
+     */
+    readonly NotarizationsRemoved: "ip_notarizations_removed";
+    /**
+     * Time in milliseconds from a proof being requested to its notarization completing.
+     */
+    readonly ProofCompletionLag: "ip_proof_completion_lag";
+};
+/**
+ * Union type of all immutable proof service metric ID string values.
+ */
+export type ImmutableProofMetricIds = (typeof ImmutableProofMetricIds)[keyof typeof ImmutableProofMetricIds];

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

@@ -0,0 +1,5 @@
+import { type ITelemetryMetric } from "@3sixty/telemetry-models";
+/**
+ * Metrics registered by the immutable proof service.
+ */
+export declare const ImmutableProofMetrics: ITelemetryMetric[];

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

@@ -0,0 +1,13 @@
+/**
+ * The topics for immutable proof event bus notifications.
+ */
+export declare const ImmutableProofTopics: {
+    /**
+     * A proof was created.
+     */
+    readonly ProofCreated: "immutable-proof:proof-created";
+};
+/**
+ * The topics for immutable proof event bus notifications.
+ */
+export type ImmutableProofTopics = (typeof ImmutableProofTopics)[keyof typeof ImmutableProofTopics];

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

@@ -0,0 +1,21 @@
+/**
+ * The types of immutable proof data.
+ */
+export declare const ImmutableProofTypes: {
+    /**
+     * Represents Immutable Proof.
+     */
+    readonly ImmutableProof: "ImmutableProof";
+    /**
+     * Represents Immutable Proof Verification.
+     */
+    readonly ImmutableProofVerification: "ImmutableProofVerification";
+    /**
+     * Represents Immutable Proof Failure.
+     */
+    readonly ImmutableProofFailure: "ImmutableProofFailure";
+};
+/**
+ * The types of immutable proof data.
+ */
+export type ImmutableProofTypes = (typeof ImmutableProofTypes)[keyof typeof ImmutableProofTypes];

package/docs/examples.md

@@ -0,0 +1,72 @@
+# Immutable Proof Models Examples
+
+These snippets show how to register data types and then use the immutable proof model contracts in request and response flows.
+
+## ImmutableProofDataTypes
+
+```typescript
+import { DataTypeHandlerFactory } from '@3sixty/data-core';
+import { ImmutableProofDataTypes, ImmutableProofTypes } from '@3sixty/immutable-proof-models';
+
+ImmutableProofDataTypes.registerTypes();
+
+const handler = DataTypeHandlerFactory.get(
+  'https://schema.3sixty.global/immutable-proof/ImmutableProof'
+);
+console.log(handler.type === ImmutableProofTypes.ImmutableProof); // true
+```
+
+## Model Contracts
+
+```typescript
+import type {
+  IImmutableProofCreateRequest,
+  IImmutableProofGetResponse,
+  IImmutableProofVerifyResponse
+} from '@3sixty/immutable-proof-models';
+
+const createRequest: IImmutableProofCreateRequest = {
+  body: {
+    document: {
+      '@context': 'https://schema.org',
+      type: 'Person',
+      name: 'Alice Example'
+    }
+  }
+};
+
+console.log(createRequest.body.document.type); // Person
+```
+
+```typescript
+import { ImmutableProofFailure, ImmutableProofTypes } from '@3sixty/immutable-proof-models';
+import type {
+  IImmutableProofGetResponse,
+  IImmutableProofVerifyResponse
+} from '@3sixty/immutable-proof-models';
+
+const getResponse: IImmutableProofGetResponse = {
+  body: {
+    '@context': ['https://www.w3.org/2018/credentials/v1'],
+    type: ['VerifiableCredential', ImmutableProofTypes.ImmutableProof],
+    issuer: 'did:iota:tst:issuer',
+    id: 'immutable-proof:01JABCDEF1234567890',
+    credentialSubject: {
+      id: 'https://example.org/documents/100',
+      proofIntegrity: 'yEr9VvYCGDh2Ww1YwQMehUy4LlW35mLhX8j8R8U6x0g='
+    }
+  }
+};
+
+const verifyResponse: IImmutableProofVerifyResponse = {
+  body: {
+    '@context': 'https://schema.3sixty.global/immutable-proof',
+    type: ImmutableProofTypes.ImmutableProofVerification,
+    verified: false,
+    failure: ImmutableProofFailure.ProofMissing
+  }
+};
+
+console.log(getResponse.body.id); // immutable-proof:01JABCDEF1234567890
+console.log(verifyResponse.body.failure); // proof-missing
+```

package/docs/reference/classes/ImmutableProofDataTypes.md

@@ -0,0 +1,25 @@
+# Class: ImmutableProofDataTypes
+
+Handle all the data types for immutable proof.
+
+## Constructors
+
+### Constructor
+
+> **new ImmutableProofDataTypes**(): `ImmutableProofDataTypes`
+
+#### Returns
+
+`ImmutableProofDataTypes`
+
+## Methods
+
+### registerTypes() {#registertypes}
+
+> `static` **registerTypes**(): `void`
+
+Register all the data types.
+
+#### Returns
+
+`void`

package/docs/reference/index.md

@@ -0,0 +1,43 @@
+# @3sixty/immutable-proof-models
+
+## Classes
+
+- [ImmutableProofDataTypes](classes/ImmutableProofDataTypes.md)
+
+## Interfaces
+
+- [IImmutableProof](interfaces/IImmutableProof.md)
+- [IImmutableProofComponent](interfaces/IImmutableProofComponent.md)
+- [IImmutableProofCredential](interfaces/IImmutableProofCredential.md)
+- [IImmutableProofDataIntegrity](interfaces/IImmutableProofDataIntegrity.md)
+- [IImmutableProofVerification](interfaces/IImmutableProofVerification.md)
+- [IImmutableProofCreateRequest](interfaces/IImmutableProofCreateRequest.md)
+- [IImmutableProofGetRequest](interfaces/IImmutableProofGetRequest.md)
+- [IImmutableProofGetResponse](interfaces/IImmutableProofGetResponse.md)
+- [IImmutableProofRemoveNotarizationRequest](interfaces/IImmutableProofRemoveNotarizationRequest.md)
+- [IImmutableProofRemoveRequest](interfaces/IImmutableProofRemoveRequest.md)
+- [IImmutableProofVerifyRequest](interfaces/IImmutableProofVerifyRequest.md)
+- [IImmutableProofVerifyResponse](interfaces/IImmutableProofVerifyResponse.md)
+- [IImmutableProofEventBusProofCreated](interfaces/IImmutableProofEventBusProofCreated.md)
+
+## Type Aliases
+
+- [ImmutableProofContexts](type-aliases/ImmutableProofContexts.md)
+- [ImmutableProofFailure](type-aliases/ImmutableProofFailure.md)
+- [ImmutableProofMetricIds](type-aliases/ImmutableProofMetricIds.md)
+- [ImmutableProofTopics](type-aliases/ImmutableProofTopics.md)
+- [ImmutableProofTypes](type-aliases/ImmutableProofTypes.md)
+
+## Variables
+
+- [CompiledImmutableProof](variables/CompiledImmutableProof.md)
+- [CompiledImmutableProofCredential](variables/CompiledImmutableProofCredential.md)
+- [CompiledImmutableProofDataIntegrity](variables/CompiledImmutableProofDataIntegrity.md)
+- [CompiledImmutableProofVerification](variables/CompiledImmutableProofVerification.md)
+- [CompiledImmutableProofFailure](variables/CompiledImmutableProofFailure.md)
+- [ImmutableProofContexts](variables/ImmutableProofContexts.md)
+- [ImmutableProofFailure](variables/ImmutableProofFailure.md)
+- [ImmutableProofMetricIds](variables/ImmutableProofMetricIds.md)
+- [ImmutableProofMetrics](variables/ImmutableProofMetrics.md)
+- [ImmutableProofTopics](variables/ImmutableProofTopics.md)
+- [ImmutableProofTypes](variables/ImmutableProofTypes.md)

package/docs/reference/interfaces/IImmutableProof.md

@@ -0,0 +1,35 @@
+# Interface: IImmutableProof
+
+Interface describing an immutable proof state.
+
+## Properties
+
+### @context? {#context}
+
+> `optional` **@context?**: \[`"https://schema.3sixty.global/immutable-proof/"`, `"https://schema.3sixty.global/common/"`\]
+
+JSON-LD Context.
+
+***
+
+### type? {#type}
+
+> `optional` **type?**: `"ImmutableProof"`
+
+JSON-LD Type.
+
+***
+
+### id? {#id}
+
+> `optional` **id?**: `string`
+
+The id of the object associated with the proof.
+
+***
+
+### proofIntegrity {#proofintegrity}
+
+> **proofIntegrity**: `string`
+
+The integrity hash of the object associated with the proof.