dssenamespacenamespace dssein-toto Statements v1 and DSSE envelopes (commons 0001-crypto FR-006): a statement says that a predicate of some type holds of its subjects, each named and identified by its digests; DSSE signs a payload of a stated type, by the pre-authentication encoding (PAE) of the two, and carries it in a JSON envelope with its signatures. Signing and verifying use Web Crypto (crypto.subtle) on keys the caller has imported as CryptoKeys, so the module has no effect beyond the computation: Ed25519, ECDSA on P-256, P-384 and P-521 (with SHA-256, SHA-384 and SHA-512, the signature in ASN.1 DER as sigstore and in-toto's own tools write it), and RSA-PSS and RSASSA-PKCS1-v1_5 with the key's hash. Verification returns the payload, or an error that says why it was refused: an envelope that is malformed, a payload type not the one expected, a key not usable, or too few valid signatures.
Taken from Stolos's src/archon/export/intoto.ts, which built a statement and an envelope for a signature callback but never verified one. What changed: the statement is generic in its predicate; the subject's digest is any map of algorithms; signing takes keys rather than a callback; verification, the envelope's decoder and the ECDSA signature form are new. Stolos's evidence bundle predicate (its predicate type, the manifest's summary and the subject list of a bundle's items) is Stolos's own domain and stays there.
import { pae, signStatement, statement, subject, verifyStatement } from "./dsse.ts";
import { unknownValue } from "@intellectual-frontiers/core";
new TextDecoder().decode(pae("http://example.com/HelloWorld", new TextEncoder().encode("hello world")));
// "DSSEv1 29 http://example.com/HelloWorld 11 hello world"
const keys = await crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]);
const s = statement([await subject("a.txt", new TextEncoder().encode("a"))], "https://example.com/Note/v1", { note: "hi" });
const signed = await signStatement(s, [{ key: keys.privateKey, keyid: "me" }]);
if (signed.kind === "ok") await verifyStatement(signed.value, [{ key: keys.publicKey, keyid: "me" }], unknownValue); // { kind: "ok", ... }dssenamespacenamespace dssedsse.STATEMENT_TYPEconstno test imports itconst STATEMENT_TYPE: "https://in-toto.io/Statement/v1"The _type of an in-toto Statement v1.
dsse.INTOTO_PAYLOAD_TYPEconstno test imports itconst INTOTO_PAYLOAD_TYPE: "application/vnd.in-toto+json"The DSSE payload type of an in-toto statement.
dsse.ResourceDescriptortypeno test imports ittype ResourceDescriptor = {
readonly name: string;
readonly digest: Readonly<Record<string, string>>;
readonly uri?: string;
readonly mediaType?: string;
readonly annotations?: Readonly<Record<string, unknown>>;
};An in-toto ResourceDescriptor as a statement's subject: its name, its digests by algorithm (sha256, ...) in lower-case hexadecimal, and what else is known of it.
dsse.Statementtypeno test imports ittype Statement<P> = {
readonly _type: typeof STATEMENT_TYPE;
readonly subject: readonly ResourceDescriptor[];
readonly predicateType: string;
readonly predicate: P;
};An in-toto Statement v1: a predicate of type predicateType that holds of the subjects.
dsse.DsseEnvelopetypeno test imports ittype DsseEnvelope = {
readonly payload: string;
readonly payloadType: string;
readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};A DSSE envelope: the payload in base64, its type, and the signatures (base64) over PAE(payloadType, payload).
dsse.DsseKeytypeno test imports ittype DsseKey = { readonly key: CryptoKey; readonly keyid?: string };A key to sign with (a private key) or verify with (a public key), and the id that names it in an envelope, if any.
dsse.DsseAlgorithmtypeno test imports ittype DsseAlgorithm =
| { readonly kind: "ed25519" }
| { readonly kind: "ecdsa"; readonly curve: "P-256" | "P-384" | "P-521" }
| { readonly kind: "rsa-pss"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" }
| { readonly kind: "rsassa-pkcs1-v1_5"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" };A signature algorithm this module signs and verifies with, as read from a key.
dsse.DsseKeyErrortypeno test imports ittype DsseKeyError = { readonly kind: "key"; readonly index: number; readonly reason: string };Why a key cannot sign or verify: its place in the list given, and the reason.
dsse.DsseErrortypeno test imports ittype DsseError =
| { readonly kind: "malformed"; readonly reason: string }
| { readonly kind: "payload-type"; readonly expected: string; readonly found: string }
| DsseKeyError
| { readonly kind: "no-valid-signature"; readonly signatures: number; readonly verified: number; readonly threshold: number };Why an envelope was refused.
dsse.StatementErrortypeno test imports ittype StatementError = DsseError | { readonly kind: "statement"; readonly error: DecodeError };Why a signed statement was refused: the envelope's error, or a payload that is not an in-toto statement with the predicate expected.
dsse.Verifiedtypeno test imports ittype Verified = { readonly payloadType: string; readonly payload: Uint8Array; readonly keys: readonly DsseKey[] };What a verified envelope carries: its payload type, its payload, and the keys that verified a signature.
dsse.subjectfunctionno test imports itfunction subject(name: string, bytes: Uint8Array<ArrayBufferLike>, more?: { readonly uri?: string | undefined; readonly mediaType?: string | undefined; readonly annotations?: Readonly<Record<string, unknown>> | undefined; }): Promise<ResourceDescriptor>A subject: the name, and the SHA-256 of the bytes; more adds a URI, a media type or annotations.
dsse.statementfunctionno test imports itfunction statement<P>(subjects: readonly ResourceDescriptor[], predicateType: string, predicate: P): Statement<P>A statement of the predicate about the subjects.
dsse.resourceDescriptorDecoderconstno test imports itconst resourceDescriptorDecoder: Decoder<ResourceDescriptor>The decoder of a ResourceDescriptor with a name and digests.
dsse.statementDecoderfunctionno test imports itfunction statementDecoder<P>(predicate: Decoder<P>): Decoder<Statement<P>>The decoder of an in-toto Statement v1 whose predicate predicate decodes.
dsse.envelopeDecoderconstno test imports itconst envelopeDecoder: Decoder<DsseEnvelope>The decoder of a DSSE envelope: its fields present, and the payload and signatures in base64.
dsse.parseEnvelopefunctionno test imports itfunction parseEnvelope(text: string): Result<DsseEnvelope, DsseError>A DSSE envelope read from JSON text, or why it is not one.
dsse.paefunctionno test imports itfunction pae(payloadType: string, payload: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBuffer>DSSE's pre-authentication encoding: DSSEv1 <len(type)> <type> <len(payload)> <payload>, the lengths in bytes as ASCII decimal.
dsse.signatureAlgorithmfunctionno test imports itfunction signatureAlgorithm(key: CryptoKey): Result<DsseAlgorithm, string>The signature algorithm of a key, or the reason it is not one this module uses.
dsse.signEnvelopefunctionno test imports itfunction signEnvelope(payloadType: string, payload: Uint8Array<ArrayBufferLike>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>The payload of the type signed by every key given (private keys), in an envelope; or the first key that cannot sign.
dsse.verifyEnvelopefunctionno test imports itfunction verifyEnvelope(envelope: DsseEnvelope, payloadType: string, keys: readonly DsseKey[], threshold?: number): Promise<Result<Verified, DsseError>>The payload of an envelope whose type is payloadType and which at least threshold of the keys given (public keys, 1 by default) each verify a signature of. A signature that names a key id is tried only with the keys of that id or of none.
dsse.signStatementfunctionno test imports itfunction signStatement<P>(s: Statement<P>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>A statement as JSON, signed by every key given, in an envelope of type application/vnd.in-toto+json.
dsse.verifyStatementfunctionno test imports itfunction verifyStatement<P>(envelope: DsseEnvelope, keys: readonly DsseKey[], predicate: Decoder<P>, threshold?: number): Promise<Result<Statement<P>, StatementError>>The statement an envelope of type application/vnd.in-toto+json carries, verified as verifyEnvelope does, its predicate decoded by predicate.
STATEMENT_TYPEconstconst STATEMENT_TYPE: "https://in-toto.io/Statement/v1"The _type of an in-toto Statement v1.
INTOTO_PAYLOAD_TYPEconstconst INTOTO_PAYLOAD_TYPE: "application/vnd.in-toto+json"The DSSE payload type of an in-toto statement.
ResourceDescriptortypeno test imports ittype ResourceDescriptor = {
readonly name: string;
readonly digest: Readonly<Record<string, string>>;
readonly uri?: string;
readonly mediaType?: string;
readonly annotations?: Readonly<Record<string, unknown>>;
};An in-toto ResourceDescriptor as a statement's subject: its name, its digests by algorithm (sha256, ...) in lower-case hexadecimal, and what else is known of it.
Statementtypeno test imports ittype Statement<P> = {
readonly _type: typeof STATEMENT_TYPE;
readonly subject: readonly ResourceDescriptor[];
readonly predicateType: string;
readonly predicate: P;
};An in-toto Statement v1: a predicate of type predicateType that holds of the subjects.
DsseEnvelopetypetype DsseEnvelope = {
readonly payload: string;
readonly payloadType: string;
readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};A DSSE envelope: the payload in base64, its type, and the signatures (base64) over PAE(payloadType, payload).
DsseKeytypetype DsseKey = { readonly key: CryptoKey; readonly keyid?: string };A key to sign with (a private key) or verify with (a public key), and the id that names it in an envelope, if any.
DsseAlgorithmtypeno test imports ittype DsseAlgorithm =
| { readonly kind: "ed25519" }
| { readonly kind: "ecdsa"; readonly curve: "P-256" | "P-384" | "P-521" }
| { readonly kind: "rsa-pss"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" }
| { readonly kind: "rsassa-pkcs1-v1_5"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" };A signature algorithm this module signs and verifies with, as read from a key.
DsseKeyErrortypeno test imports ittype DsseKeyError = { readonly kind: "key"; readonly index: number; readonly reason: string };Why a key cannot sign or verify: its place in the list given, and the reason.
DsseErrortypeno test imports ittype DsseError =
| { readonly kind: "malformed"; readonly reason: string }
| { readonly kind: "payload-type"; readonly expected: string; readonly found: string }
| DsseKeyError
| { readonly kind: "no-valid-signature"; readonly signatures: number; readonly verified: number; readonly threshold: number };Why an envelope was refused.
StatementErrortypeno test imports ittype StatementError = DsseError | { readonly kind: "statement"; readonly error: DecodeError };Why a signed statement was refused: the envelope's error, or a payload that is not an in-toto statement with the predicate expected.
Verifiedtypeno test imports ittype Verified = { readonly payloadType: string; readonly payload: Uint8Array; readonly keys: readonly DsseKey[] };What a verified envelope carries: its payload type, its payload, and the keys that verified a signature.
subjectfunctionfunction subject(name: string, bytes: Uint8Array<ArrayBufferLike>, more?: { readonly uri?: string | undefined; readonly mediaType?: string | undefined; readonly annotations?: Readonly<Record<string, unknown>> | undefined; }): Promise<ResourceDescriptor>A subject: the name, and the SHA-256 of the bytes; more adds a URI, a media type or annotations.
statementfunctionfunction statement<P>(subjects: readonly ResourceDescriptor[], predicateType: string, predicate: P): Statement<P>A statement of the predicate about the subjects.
resourceDescriptorDecoderconstno test imports itconst resourceDescriptorDecoder: Decoder<ResourceDescriptor>The decoder of a ResourceDescriptor with a name and digests.
statementDecoderfunctionfunction statementDecoder<P>(predicate: Decoder<P>): Decoder<Statement<P>>The decoder of an in-toto Statement v1 whose predicate predicate decodes.
envelopeDecoderconstconst envelopeDecoder: Decoder<DsseEnvelope>The decoder of a DSSE envelope: its fields present, and the payload and signatures in base64.
parseEnvelopefunctionfunction parseEnvelope(text: string): Result<DsseEnvelope, DsseError>A DSSE envelope read from JSON text, or why it is not one.
paefunctionfunction pae(payloadType: string, payload: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBuffer>DSSE's pre-authentication encoding: DSSEv1 <len(type)> <type> <len(payload)> <payload>, the lengths in bytes as ASCII decimal.
signatureAlgorithmfunctionfunction signatureAlgorithm(key: CryptoKey): Result<DsseAlgorithm, string>The signature algorithm of a key, or the reason it is not one this module uses.
signEnvelopefunctionfunction signEnvelope(payloadType: string, payload: Uint8Array<ArrayBufferLike>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>The payload of the type signed by every key given (private keys), in an envelope; or the first key that cannot sign.
verifyEnvelopefunctionfunction verifyEnvelope(envelope: DsseEnvelope, payloadType: string, keys: readonly DsseKey[], threshold?: number): Promise<Result<Verified, DsseError>>The payload of an envelope whose type is payloadType and which at least threshold of the keys given (public keys, 1 by default) each verify a signature of. A signature that names a key id is tried only with the keys of that id or of none.
signStatementfunctionfunction signStatement<P>(s: Statement<P>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>A statement as JSON, signed by every key given, in an envelope of type application/vnd.in-toto+json.
verifyStatementfunctionfunction verifyStatement<P>(envelope: DsseEnvelope, keys: readonly DsseKey[], predicate: Decoder<P>, threshold?: number): Promise<Result<Statement<P>, StatementError>>The statement an envelope of type application/vnd.in-toto+json carries, verified as verifyEnvelope does, its predicate decoded by predicate.