[andpuc23]

Description of change

Three parts:

Part	What	Files
1	New ontology SignatureRequest (d5874436-fb13-46b2-b0f1-f2882c261fa3, domain governance), in the vault of the party the proposed record belongs to	services/ontology/schemas/signatureRequest.json
2	New BindingDocument type consent, in the signer's own vault	definitions.ConsentData in services/ontology/schemas/binding-document.json (with consent in the type enum and a per-type rule), plus the eVault changes below
3	Company (0f9a3cb8-4a9f-4b5f-a1fa-3a4c2eb1f402) gets the organisation's full legal identity and is titled Organization	services/ontology/schemas/company.json, docs/docs/W3DS Protocol/Company-Delegation.md

What it's for

Some records must not be written until specific people have signed: a Delegation needs its director's grant, and a platform may require the person receiving a role to consent; a board change, an admission or a mandate can need several people. Today the waiting state of such a change has nowhere to live in W3DS. It ends up in a platform database, so only that platform can see it, the people concerned can't prove what they agreed to, and nothing reaches their wallets.

• SignatureRequest puts that state in the owner's vault: the proposed record and its hash, one slot per needed signature (with who may fill it: "Xolani", or "any one director"), and the request's status.
• A consent BindingDocument is how a person consents: it sits in their own vault, so they keep the proof, and the eID Wallet can prompt for it exactly as it already prompts for a pending social_connection (fix(eid-wallet): accept, decline or cancel a social binding from the list #1147, fix(eid-wallet): show an incoming social request on the home screen, and stop × from declining it #1164).
• Grants need no new record: an authority slot holds the director's w3ds-grant/v1 signature over the proposed record, which becomes that record's authorization when it is written. The director signs once.

The first writer is Ruby (an organisation and roles platform, a fork of eCommons CORE). When @sarah, a director, puts @XOLANI into the role head:

1. Ruby writes a SignatureRequest in the organisation's vault proposing the Delegation, with a subject slot for Xolani (consent) and an authority slot for Sarah (grant).
2. Ruby creates a consent BindingDocument in Xolani's vault (signed with Ruby's own key as the owner signature) and posts a Message in the organisation's Chat: "@sarah wants @XOLANI to become head, signatures needed: @XOLANI, @sarah". The eVault notifies the chat's participants.
3. Xolani's wallet finds the document waiting for his signature and prompts him; he signs (createBindingDocumentSignature). Sarah signs the grant through Ruby.
4. With every slot signed, Ruby writes the Delegation (Sarah's grant as its authorization) and marks the request executed.

Nothing in either part is specific to Ruby or to Delegations.

Why not an existing schema

• Delegation / Role / Company can't be pending: status is active or revoked, and their authorization is mandatory, so an unsigned proposal is not a valid record. They have room for one signature (the grantor's), and additionalProperties: false rules out adding a subject's consent.
• SigningEnvelope (256510c7…) is the closest match and the model we follow (a canonical record plus each signer's own record in their vault). But it is built around a PDF (fileUri, plaintextSha256 of the document, encryption, form-field versioning), puts the canonical envelope on the initiator's vault and says process state lives in the platform database. Here the subject is a proposed record, the request belongs in the owner's vault and its state must be in the vault. Extending it would change its meaning for docusigner's existing data.
• EIDSignature, Signature and Charter Signature are signatures on a PDF envelope, a file and a group charter respectively.
• BindingDocument fits the consent itself, hence part 2: a statement about its subject, created by one party and counter-signed by the subject, with the eVault checking each signature on the dedicated mutations, and an existing wallet prompt. It can't hold the request (several signers, eligibility, status), which is part 1.

Part 1: SignatureRequest

• Slots, not a list of people. Each slot needs one signature from any of its eligibleENames. "A director" is one slot listing every director. Every slot must be signed; one decline declines the request.
• Capacity says why: subject, authority, approver, witness.
• Signature kind says how: grant (a w3ds-grant/v1 signature held in the slot's grant, in the same shape as Role/Delegation/Company authorization) or consent (a consent BindingDocument in the signer's vault, named by bindingDocumentId).
• The proposal is fixed. proposal.record is the record as it will be stored apart from authorization, recordSha256 its hash, and recordId the MetaEnvelope id it will be written under, chosen in advance. A different proposal is a new request.
• Who may read. A request names the people involved and what is proposed; platforms should give it an _acl readable by the eligible signers, the requester and the owner's admins.
• Domain: governance (mandates and permissions), where role and board changes belong. legal (contracts and signatures) was considered; a SignatureRequest authorises a change in who may act for the owner rather than recording an agreement.

Part 2: the consent BindingDocument type

data (ConsentData): kind: "consent", a statement the wallet shows ("Become head of Test Org, requested by @sarah"), the request it answers (requestOwnerEName, requestId, slotId), the requesterEName, and the proposal it covers (ontology, recordId, recordSha256, copied from the request). Signatures cover the BindingDocument's canonical form (stableStringify({ subject, type, data })), so a consent names exactly one request, slot and proposal and can't be reused.

Owner signature: the platform that created the request (Ruby), with its own key. Counterparty: must be the subject, as for social_connection. Declining is deleting the document, as for social_connection.

Who may read a consent. createBindingDocument takes no access policy today and stores the document readable by its subject only. The recommended shape is an optional _acl on createBindingDocument, so the requesting organisation can read the consent from the start. Until the eVault accepts one, the platform attaches the _acl right after creating the document with updateMetaEnvelope, acting for the subject; the eVault keeps it through later signatures. Ruby does this.

Verification. The dedicated BindingDocument mutations check every signature, but the generic updateMetaEnvelope path does not protect BindingDocuments, nor Role, Delegation or Company: enforcing company authority on writes (#1193) was closed without merging. Anyone relying on a consent or grant therefore re-checks its signatures (for a grant, checkGrantAuthorization), as they already must for Role and Delegation.

The platform's key. The eVault verifies the owner signature against the keys the Registry certifies for the signer's eName (keyBindingCertificates in /whois). A platform eName assigned by GitW3 starts with none. GitW3's deployment key doesn't fill the gap, since it is bound to the separate deployment eName. The platform registers a key for its own eName instead: it generates an ECDSA P-256 pair server-side, keeps the private key out of the repository, and sends the public key to its eVault with PATCH /public-key (X-ENAME the platform eName, a Registry token whose platform claim is that eName); /whois then serves a key binding certificate for it, and the platform's signatures verify.

Notifications need no eVault change. The eID Wallet finds an unsigned consent document in its own vault the way it finds a pending social_connection (the home screen's periodic check), and the requesting platform tells the people concerned by posting a Message in the relevant Chat, for which the eVault already notifies every participant's wallet. Ruby posts "@sarah wants @XOLANI to become head. Signatures needed: @XOLANI, @sarah" in the organisation's Chat.

In binding-document.json that is three edits: "consent" in properties.type.enum; ConsentData under definitions; and an allOf entry like the existing per-type ones, so a consent document's data must be ConsentData:

{
  "if": { "properties": { "type": { "const": "consent" } }, "required": ["type"] },
  "then": { "properties": { "data": { "$ref": "#/definitions/ConsentData" } } }
}

Changes besides the ontology:

Where	Change
infrastructure/evault-core/src/core/types/binding-document.ts	"consent" in BindingDocumentType; a BindingDocumentConsentData interface
infrastructure/evault-core/src/core/protocol/typedefs.ts	consent in the GraphQL BindingDocumentType enum
infrastructure/evault-core/src/core/protocol/graphql-server.ts	"consent" in both VALID_BINDING_DOCUMENT_TYPES lists
infrastructure/evault-core/src/services/BindingDocumentService.ts	a case "consent" in validateBindingDocumentData (the shape above), and in addCounterpartySignature the same rule as social_connection: the counterparty must be the subject
infrastructure/evault-core/src/services/BindingDocumentService.spec.ts	creating a consent, rejecting malformed consent data, only the subject counter-signing

Not in this PR, a follow-up for the eID Wallet: infrastructure/eid-wallet/src/lib/utils/socialBinding.ts, pendingSocialRequest.ts and /main should look for unsigned consent documents as well as social_connection ones, and show the consent prompt with data.statement and the requester; Accept adds the signature, Decline deletes. Until then a platform can collect the consent signature with a w3ds://sign request over the document's canonical form, which is what Ruby does.

Part 3: Organization (formerly Company)

The organisation's full legal identity in the record

Adds four optional fields next to legalName, registrationNumber and jurisdiction:

Field	What
legalForm	Legal form in its jurisdiction, as registered ("BV", "stichting", "vereniging", "GmbH", "LLC")
foundingDate	Date the organisation was legally founded (format: date)
iban	IBAN of the account payments to the organisation go to, without spaces (pattern-checked)
statutesFileUri	The statutes (articles of association), as a w3ds://file URI

It also says that address is the registered address (the legal seat), not a visiting address.

Why here: platforms keep these details elsewhere today. eCommons CORE, for example, has them in its own Organization record, which several platforms write. In this record they are covered by the director's signature in authorization, so only a director can change them. In particular, nobody can swap the IBAN payers see without a director's signature. Details people edit day to day (a display name, branding, a visiting address) stay out of it, because a board signature for every edit would be too much.

The section "Company: born with its board" in docs/docs/W3DS Protocol/Company-Delegation.md gets a paragraph saying so.

Titled "Organization"

The record describes any organisation with a board: a company, a foundation, an association, a cooperative. So its title becomes Organization, and the description notes it was titled "Company" until 2026-10. The schemaId, the fields and the vault type company in /whois are unchanged, and nothing looks the schema up by title (the Ontology service matches titles only for the Domain schema). If reviewers prefer to keep "Company", that is its own commit and can be dropped.

Issue Number

None. Builds on the Company, Role and Delegation ontologies (#1191); see the note on #1193 under Verification.

Type of change

• New (a change which implements a new feature)
• Update (a change which updates existing functionality)

How the change has been tested

• pnpm -F=evault-core test: 27 files, 372 tests pass, including 3 new ones in BindingDocumentService.spec.ts (Neo4j test container).

• evault-core: tsc --noEmit clean. All 69 ontology schemas pass the draft-07 meta-schema with unique ids, and the ontology service serves both changed schemas.

• End to end on a local dev stack (registry, provisioner and eVault-core at 215890c plus this change, signing with the dev sandbox wallet), driven by Ruby: a director creates a Role, assigns a member, the member's consent document is created in their vault and counter-signed, and the Delegation is written with the director's grant as its authorization; declining and withdrawing too. checkGrantAuthorization from @metastate-foundation/delegation accepts the written Role, Delegation and revocation. 48 SignatureRequests and 8 consent documents written there validate against these schemas.

• Organization: company.json passes the draft-07 meta-schema. A record with every new field validates.

• Organization: refused are an IBAN with spaces or lower case, a founding date not in YYYY-MM-DD, a statutes link that isn't a w3ds://file URI, and a non-string legal form.

• Organization: A record without the new fields still validates, so existing Company records are unaffected.

• Organization: The ontology service starts with the change and serves the schema under the title "Organization", with the four new fields.

Change checklist

• I have ensured that the CI Checks pass locally (evault-core tests; check and check-format have no tasks for the changed packages)
• I have removed any unnecessary logic
• My code is well documented
• I have signed my commits
• My code follows the pattern of the application
• I have self reviewed my code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 803ce427-f10e-46ba-bd15-c681a3f13eea

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}