feat(signature): add org.accordproject.signature@1.0.0

[niallroche]

Closes #<N/A>

Reposition org.accordproject.signature from a narrow ContractSigned transaction into a general model of verifiable attestations over contract and agreement content.

Changes

• Add org.accordproject.signature@1.0.0.
• Add the Attestation envelope, Signatory, ValidityWindow, Delegation, AttestationStatus, SignatureMethod, and AssuranceLevel.
• Add an abstract Proof concept with OpaqueProof as an escape hatch for protocol-specific proof formats.
• Bind attested content via org.accordproject.crypto@1.0.0.ContentHash, so attestations carry digest algorithm, value, encoding, and optional canonicalization metadata rather than a bare string.
• Keep the existing ContractSigned extends Request transaction and enrich it with optional Attestation[] data, giving older consumers a familiar migration path while newer integrations can inspect structured signature metadata.

Flags

• This is a 1.0.0 version because the signature namespace is being repositioned from a narrow transaction model into a stable signature/attestation model.
• Runtime and contract imports intentionally remain aligned with signature@0.3.0 for compatibility.
• Part of the agentic-commerce model family alongside crypto and x402, with a2a/ap2 to follow.
• Aligns with the reference-implementation signing work in accordproject/apap#182.

Screenshots or Video

N/A

Related Issues

• Pull Request verifiable agreement signatures apap#182 (related to identity)

Author Checklist

• Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
• Vital features and changes captured in unit and/or integration tests
• Commits messages follow AP format
• Extend the documentation, if necessary
• Merging to master from fork:branchname

[mttrbrts]

Great work on this model — a few suggestions for consideration:

Typed proof subtypes

OpaqueProof works as an escape hatch, but a ProviderProof extends Proof with structured fields for common evidence would make verification more tractable:

concept ProviderProof extends Proof {
    o String providerId          // e.g. "docusign", "adobe-sign", "wet-ink"
    o String envelopeOrSessionId optional  // provider's transaction/session identifier
    o String recipientId optional          // provider's per-recipient identifier
    o String certificateUri optional       // URL to provider-issued certificate
    o String ipAddress optional            // signer's IP at time of signing
    o String userAgent optional            // browser/device context
}

For DocuSign this maps directly: providerId: "docusign", envelopeOrSessionId holds the envelope UUID, certificateUri points to the Certificate of Completion. Other providers (Adobe Sign, HelloSign, wet-ink scan workflows) would populate the same fields differently.

Identity verification method

AssuranceLevel captures the tier of assurance but not the mechanism used to verify identity before signing. Providers record this granularly and it directly supports assurance level claims:

enum IdentityVerificationMethod {
    o EMAIL_LINK
    o SMS_OTP
    o PHONE_CALL
    o KNOWLEDGE_BASED_AUTH
    o ID_DOCUMENT_SCAN
    o ACCESS_CODE
    o NONE
    o CUSTOM
}

concept IdentityVerification {
    o IdentityVerificationMethod method
    o DateTime verifiedAt optional
    o String providerId optional
    o String customName optional
}

Add o IdentityVerification identityVerification optional to Attestation. DocuSign's ID Verify maps to ID_DOCUMENT_SCAN; standard email-link signing maps to EMAIL_LINK. This makes the backing evidence for ADVANCED vs STANDARD assurance explicit rather than implied.

Status decline/revocation reason

AttestationStatus has REVOKED but no way to record why. Providers capture decline reasons verbatim:

concept AttestationStatusDetail {
    o AttestationStatus status
    o String reason optional
    o DateTime timestamp optional
}

Replace o AttestationStatus status default="CREATED" on Attestation with o AttestationStatusDetail status.

Multi-document support

A single ContentHash per attestation assumes one document per signing action. Many providers bundle multiple documents into one signing event (envelopes, signing packages). Wrapping it allows a signer's single action to cover multiple documents:

concept DocumentAttestation {
    o String documentId optional    // provider's document sequence/ID within the bundle
    o String documentName optional
    o ContentHash contentHash
}

Replace o ContentHash contentHash on Attestation with o DocumentAttestation[] documents.

---

AP stack integration

Template archive reference on ContractSigned. The --> Contract contract relationship gives you the contract instance, and the CTO class implicitly encodes the template name. But the specific archive version (the .cta file) that produced the contract isn't captured. Two contracts can share the same CTO class but come from different archive versions with different logic or clause text. A small addition closes this:

concept TemplateReference {
    o String identifier        // e.g. "latedeliveryandpenalty"
    o String version           // e.g. "0.15.0"
    o ContentHash archiveHash optional  // hash of the .cta archive
}

transaction ContractSigned extends Request {
    --> Contract contract
    o TemplateReference template optional
    o Attestation[] attestations optional
}

Content representation. contentHash is ambiguous about what was hashed — Concerto JSON, rendered CiceroMark, plaintext, PDF. Signatories typically sign rendered text, not data models. An explicit field would let verifiers know what to re-hash:

enum ContentRepresentation {
    o CONCERTO_JSON
    o CICEROMARK
    o PLAINTEXT
    o PDF
    o CUSTOM
}

Add o ContentRepresentation contentRepresentation optional to DocumentAttestation (or ContentHash directly, though the latter has broader reuse implications).

---

Happy to elaborate on any of these or sketch out how they'd compose with the existing crypto@1.0.0 model.

[niallroche]

Thanks for the detailed review @mttrbrts and the DocuSign steer makes this more in line with industry norms. All six of your suggestions are now in, across the two commits above.

Adopted as proposed:

• 'ProviderProof extends Proof', alongside the existing 'OpaqueProof' escape hatch
• 'IdentityVerificationMethod' + 'IdentityVerification', added to 'Attestation'
• 'AttestationStatusDetail' replacing the bare status enum
• 'DocumentAttestation[]' documents replacing the single 'contentHash'
• 'TemplateReference' on 'ContractSigned'
• 'ContentRepresentation' on 'DocumentAttestation'

One addition beyond your list, in its own commit so it can be dropped independently: a 'WALLET_KEY_CONTROL' value on 'IdentityVerificationMethod'. Wallet-based signing otherwise has to fall back to 'CUSTOM' + 'customName', which understates something that's becoming common rather than exceptional. The argument for a first-class value is that it differs in kind from the others: in every other method a third party vouches for the identity, whereas here the ledger does. providerId carries how the key was resolved. Happy to revert it to 'CUSTOM' if you'd rather keep the enum provider-oriented.

Feedback on two of yours, having built against this model in an x402/blockchain flow: the multi-document and content-representation changes earned their keep immediately. A single wallet signature there covers two documents that are hashed differently by design — the terms document (SHA-256 over rendered text, 'PLAINTEXT') and the acceptance statement binding the signer to a specific offer (Keccak-256 over RFC 8785 canonical 'JSON', 'CONCERTO_JSON'). With one contentHash and no representation field there was no way to express that, and a verifier had no way to know what to re-hash. Both suggestions were exactly right.

Model validates against crypto@1.0.0, contract@0.2.0 and runtime@0.2.0.

[mttrbrts]

We should also bump these to 1.0.0

[mttrbrts]

Should this still have default=CREATED