diff --git a/a2p-campaign/a2p-campaign.schema.json b/a2p-campaign/a2p-campaign.schema.json index a3808b6..50931da 100644 --- a/a2p-campaign/a2p-campaign.schema.json +++ b/a2p-campaign/a2p-campaign.schema.json @@ -1,226 +1,445 @@ { - "$id": "EK3YbEFp3zUuHPsGrLRzwr6zWBXcOFJNTTBqezXd_2yf", - "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "ENjbevI70JxcQJaTrUQxMr4Ylcw0gbjfG2_skJyXy5XQ", + "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "A2P Campaign Credential", - "description": "A credential issued to a brand for A2P 10DLC messaging campaigns", + "description": "A credential issued to an organization that represents a registered A2P messaging campaign and the telephone numbers associated with that campaign.", "type": "object", - "credentialType": "a2p-campaign-credential", - "version": "1.0.0", + "version": "2.0.0", "required": [ "v", "d", - "u", "i", "ri", "s", "a", - "e", "r" ], "properties": { "v": { - "description": "Version", - "type": "string" + "description": "Version string using ACDC conventions, encoding protocol, serialization, and size.", + "type": "string", + "pattern": "^ACDC[0-9]{2}[A-Z]{4}[0-9a-f]{6}_$", + "examples": [ + "ACDC10JSON0005c8_" + ] }, "d": { - "description": "Credential SAID", - "type": "string" + "description": "SAID of the credential (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "u": { - "description": "A salty nonce", - "type": "string" + "description": "A salty nonce (high-entropy random value) used to prevent rainbow-table attacks on the credential SAID.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "Issuer AID", - "type": "string" + "description": "AID of the issuer (the party asserting the campaign).", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EDC0Sj0CPYd70zUSY2ehvm7Z4kwZigugiA84wuS7lK2H", + "BCmx-dBiozRlK5MfRnznAHl9kmXjB3t-zxrE3hIIYkeS" + ] }, "ri": { - "description": "Credential status registry", - "type": "string" + "description": "SAID of the issuer's ACDC credential status registry.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EiySMSMLRrpt9AD_b34VEtUD6tDO0yaGoWCwB1iyJOgY" + ] }, "s": { - "description": "Schema SAID", - "type": "string" + "description": "SAID of this schema (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EFtg-VSIdmBRAH2bNMIkfuAyNShqN8volGPsl5ZQZbTp" + ] }, "a": { "oneOf": [ { - "description": "Attributes block SAID", - "type": "string" + "description": "SAID of attributes block.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EAS6jFIgA_WqWEIX6bQTi6Hvdox3GuyRbDKY8JCEfyZG" + ] }, { - "$id": "ENaGw3QznDw6OuygdexMzSmC-jVGoxSkrdJd76xthUqL", + "$id": "EJ1chJIJ5V75UtiTWx4lMspvLrUwGFycJrt7wj_TnyfR", "description": "Attributes block", "type": "object", + "required": [ + "d", + "i", + "dt", + "brandId", + "campaignId", + "usecase", + "authorizedServiceProvider" + ], "properties": { "d": { - "description": "Attributes block SAID", - "type": "string" + "description": "SAID of the attributes block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EAS6jFIgA_WqWEIX6bQTi6Hvdox3GuyRbDKY8JCEfyZG" + ] }, "u": { - "description": "A salty nonce", - "type": "string" + "description": "A salty nonce for the attributes block, enabling selective disclosure.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "AID of issuee (org that will send messages in this campaign)", - "type": "string" + "description": "AID of the organization approved to originate traffic for this campaign.", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EK2r6EnDXre2pecTBO8s99j4OtNaaDIhVyr7uGugDhmp" + ] }, "dt": { - "description": "Issuance datetime, ISO-8601 datetime string", + "description": "Issuance date-time (when the ACDC was signed), as an ISO-8601 datetime string with timezone.", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": [ + "2024-11-13T20:20:39.000000+00:00" + ] }, "brandId": { - "description": "A non-verifiable, non-cryptographic identifier for the org that will send messages in this campaign -- e.g., an LEI, ISIN code, S&P company ID, DUNS number, etc.", - "type": "string" + "description": "Legal identifier for the organization approved for the campaign -- e.g., an LEI, ISIN code, S&P company ID, DUNS number, etc.", + "type": "string", + "minLength": 2, + "maxLength": 64, + "examples": [ + "5493001KJTIIGC8Y1R12" + ] }, "campaignId": { - "description": "Unique campaign identifier", + "description": "Unique campaign identifier assigned by the campaign approval authority or registry.", + "type": "string", + "minLength": 3, + "maxLength": 32, "examples": [ "CVN1LXI" - ], - "type": "string" + ] }, - "campaignType": { - "description": "Campaign type; see strings that identify standard use cases on page 7 of https://www.10dlc.org/tcr_quick_reference_guide.pdf", + "usecase": { + "description": "Campaign use case category. Values should align with the applicable campaign registry or governance framework.", + "type": "string", "examples": [ "2FA", + "Account Notification", + "Customer Care", + "Delivery Notification", + "Fraud Alert", + "Higher Education", + "Marketing", "Public Service Announcement", - "Low Volume Mixed" - ], - "type": "string" + "Security Alert" + ] }, "startDate": { - "description": "Campaign start date", + "description": "Campaign start date-time, as an ISO-8601 datetime string with timezone.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2024-11-13T20:20:39.000000+00:00" + ] }, "endDate": { - "description": "Date when campaign expires", + "description": "Campaign expiration date-time, as an ISO-8601 datetime string with timezone.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2025-11-13T20:20:39.000000+00:00" + ] }, - "telephoneNumbers": { - "description": "Telephone Numbers for the campaign", + "numbers": { + "description": "Array of number expressions representing telephone numbers allocated to the brand. Each expression is either a single E164 number (e.g., '+15551234567') or an inclusive range denoted by a hyphen between two E164 numbers (e.g., '+15551230000-+15551239999').", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "string", - "description": "Telephone number in E164 format" - } + "description": "A single E164 telephone number or an inclusive range. Single number: '+' followed by 7-15 digits. Range: two E164 numbers separated by a hyphen (e.g., '+15551230000-+15551239999').", + "pattern": "^\\+[1-9][0-9]{6,14}(-\\+[1-9][0-9]{6,14})?$" + }, + "examples": [ + [ + "+15551234567" + ], + [ + "+15551230000-+15551239999" + ], + [ + "+15551234567", + "+442071234567" + ], + [ + "+15551230000-+15551239999", + "+15558880000-+15558889999" + ], + [ + "+15551234567", + "+15559876543", + "+442071234567", + "+81312345678" + ] + ] }, "authorizedServiceProvider": { - "description": "Authorized service provider", - "type": "string" + "description": "Service provider authorized to originate or manage traffic for this campaign.", + "type": "string", + "minLength": 2, + "maxLength": 64, + "examples": [ + "Twilio" + ] }, "campaignAttributes": { - "description": "The Campaign and content attributes object contains a series of Yes or No questions related to the particular features of the campaign", + "description": "Campaign and content attributes used to evaluate the campaign under the applicable governance framework.", "type": "object", + "required": [ + "subscriberOptIn", + "subscriberOptOut" + ], "properties": { "subscriberOptIn": { - "description": "Indicate whether campaign collect and process customer opt-ins", - "type": "boolean" + "description": "Whether the campaign collects and processes subscriber opt-ins.", + "type": "boolean", + "examples": [ + true + ] }, "subscriberOptOut": { - "description": "Indicate whether campaign collect and process customer opt-outs", - "type": "boolean" + "description": "Whether the campaign collects and processes subscriber opt-outs.", + "type": "boolean", + "examples": [ + true + ] }, "subscriberHelp": { - "description": "Indicate whether subscribers can contact the message sender after sending the HELP keyword", - "type": "boolean" + "description": "Whether subscribers can contact the sender after sending the HELP keyword or equivalent support request.", + "type": "boolean", + "examples": [ + true + ] }, "embeddedLink": { - "description": "Indicate whether campaign messages will use an embedded link", - "type": "boolean" + "description": "Whether campaign messages may contain embedded links.", + "type": "boolean", + "examples": [ + false + ] }, "affiliateMarketing": { - "description": "Indicate whether the campaign involves affiliate marketing", - "type": "string" + "description": "Whether the campaign involves affiliate marketing.", + "type": "boolean", + "examples": [ + false + ] } }, - "additionalProperties": true, - "required": [ - "subscriberOptIn", - "subscriberOptOut", - "subscriberHelp" - ] + "additionalProperties": true } }, - "additionalProperties": false, - "required": [ - "i", - "dt", - "brandId", - "campaignId", - "campaignType", - "startDate", - "endDate", - "telephoneNumbers", - "authorizedServiceProvider", - "campaignAttributes" - ] + "additionalProperties": true } ] }, "e": { "oneOf": [ { - "description": "Edges block SAID", - "type": "string" + "description": "SAID of edges block.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EOS9BUu6iHS6QaTADgHWcWG36tsKYY3g_z3nCkrnbBMr" + ] }, { - "$id": "EJrEovSBvm4odgfVI9zldtlju8_lD2m1gDiryDqvB8Lt", + "$id": "ECcoiTmWs6GwR3iIOkBEeG6RpxhtvKylXlMREccxwhtg", "description": "Edges block", "type": "object", + "required": [ + "d" + ], "properties": { "d": { - "description": "Edges block SAID", - "type": "string" + "description": "SAID of the edges block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EOS9BUu6iHS6QaTADgHWcWG36tsKYY3g_z3nCkrnbBMr" + ] }, - "le": { - "description": "Chain to legal entity vLEI credential", + "issuer": { + "description": "Credential that proves the identity of the issuer.", "type": "object", "properties": { "n": { - "description": "SAID of Legal Entity vLEI Credential issued by a Qualified vLEI issuer to a Legal Entity", - "type": "string" + "description": "SAID of a credential that proves the identity of the issuer.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] + }, + "s": { + "description": "SAID of the schema that the issuer identity credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9" + ] + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false, + "required": [ + "n", + "s", + "o" + ] + }, + "tnalloc": { + "description": "Chain to a Telephone Number Allocation credential proving right to use the campaign telephone numbers.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of the Telephone Number Allocation credential.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] + }, + "s": { + "description": "SAID of the Telephone Number Allocation schema.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EJ9YoTJ81TcQ_pS9GmU2UbVURRm3ylnx_Wr1GbKjg0QP" + ] + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false + }, + "brandid": { + "description": "Chain to a credential that identifies the brand or organization associated with this campaign.", + "type": "object", + "properties": { + "n": { + "description": "SAID of a credential that proves the brand identity.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "s": { - "description": "SAID of Legal Entity vLEI Credential schema", + "description": "SAID of the schema that the brand identity credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z" + ] + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", "type": "string", - "const": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] } }, "additionalProperties": false, "required": [ "n", - "s" + "s", + "o" ] } }, - "additionalProperties": false, - "required": [ - "d", - "le" - ] + "additionalProperties": true } ] }, "r": { "oneOf": [ { - "description": "Rules section SAID", - "type": "string" + "description": "SAID of rules block (Blake3-256 digest in CESR compact encoding)", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" }, { - "$id": "EIR5KMj9Z1Qj6gxn8O_93boQs4ApN1RPX3blcz6WzEB2", + "$id": "EKcJyuGHv_e_Ia9aeH_UarSr2GnPZpFUIah47YkaDC-4", "description": "Rules detail", "type": "object", + "required": [ + "d", + "governance" + ], "properties": { "d": { - "description": "Rule section SAID", - "type": "string" + "description": "SAID of the rules block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EMS9_VeDinkCdVlMVJKwbeBrsjnVj8VO1OS0walgg05X" + ] + }, + "governance": { + "description": "Statement identifying the governance framework under which this credential was issued.", + "type": "string", + "examples": [ + "Issued under governance published at https://provenant.net/governance/a2p-campaign/" + ] }, "brandPrivacy": { "description": "Brand Privacy Disclaimer", @@ -233,6 +452,9 @@ { "description": "Rule detail", "type": "object", + "required": [ + "l" + ], "properties": { "l": { "description": "Associated legal language", @@ -240,9 +462,6 @@ "const": "Verifiers agree that, if they learn the identity of a brand as a sender of SMS messages by verifying this credential, they will not use this information to infer or model relationships between the brand and service providers." } }, - "required": [ - "l" - ], "additionalProperties": false } ] @@ -256,8 +475,11 @@ "const": "Senders of SMS messages agree that their reputation as a sender may be non-repudiably associated with messages that cite this campaign, exactly and only to the extent that the messages are signed by an entity cryptographically authorized to represent the brand." }, { - "description": "rule detail", + "description": "Rule detail", "type": "object", + "required": [ + "l" + ], "properties": { "l": { "description": "Associated legal language", @@ -265,20 +487,12 @@ "const": "Senders of SMS messages agree that their reputation as a sender may be non-repudiably associated with messages that cite this campaign, exactly and only to the extent that the messages are signed by an entity cryptographically authorized to represent the brand." } }, - "required": [ - "l" - ], "additionalProperties": false } ] } }, - "additionalProperties": false, - "required": [ - "d", - "brandPrivacy", - "nonrepudiableBySig" - ] + "additionalProperties": true } ] } diff --git a/a2p-campaign/example-a2p-campaign.json b/a2p-campaign/example-a2p-campaign.json index 132a9f8..a7fc5ce 100644 --- a/a2p-campaign/example-a2p-campaign.json +++ b/a2p-campaign/example-a2p-campaign.json @@ -1,23 +1,27 @@ { "v": "ACDC10JSON0005c8_", "d": "Ez6QKIKLzrGqpq4v9Bj908pQanoRKwOgBXjPW-w-P_8Q", - "i": "Ez6QKIKLzrGqpq4v9Bj908pQanoRKwOgBXjPW-w-P_8Q", + "u": "0AHcgNghkDaG7ts1Bv8wkv3b", + "i": "EDC0Sj0CPYd70zUSY2ehvm7Z4kwZigugiA84wuS7lK2H", "ri": "EiySMSMLRrpt9AD_b34VEtUD6tDO0yaGoWCwB1iyJOgY", - "s": "ELtCd1s8TXGNYC2VUVzBtFcY73ec9pBMZg1LCfGP6LJQ", + "s": "EN-GIMlGnS188KLQS26IH11b3J7uw6TTK2p5Uuy0CCy0", "a": { "d": "EAS6jFIgA_WqWEIX6bQTi6Hvdox3GuyRbDKY8JCEfyZG", + "u": "0AHcgNghkDaG7ts1Bv8wkv3b", "i": "EK2r6EnDXre2pecTBO8s99j4OtNaaDIhVyr7uGugDhmp", + "dt": "2024-11-13T20:20:39.000000+00:00", + "brandId": "5493001KJTIIGC8Y1R12", "campaignId": "CVN1LXI", - "campaignType": "Fraud Alert", - "startDate": "2024-11-13T20:20:39+00:00", - "endDate": "2024-12-13T20:20:39+00:00", - "telephoneNumbers": [ + "usecase": "Fraud Alert", + "startDate": "2024-11-13T20:20:39.000000+00:00", + "endDate": "2025-11-13T20:20:39.000000+00:00", + "numbers": [ "+18013612446" ], "authorizedServiceProvider": "Twilio", "campaignAttributes": { "subscriberOptIn": true, - "subscriberOptOut": false, + "subscriberOptOut": true, "subscriberHelp": true, "embeddedLink": false, "affiliateMarketing": false @@ -25,14 +29,26 @@ }, "e": { "d": "EOS9BUu6iHS6QaTADgHWcWG36tsKYY3g_z3nCkrnbBMr", - "le": { - "n": "EOy_g1RrcQW_uh63l9SH7TGflNefu3Pe2C3asw_H2CFv", - "s": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" + "issuer": { + "n": "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC", + "s": "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9", + "o": "I2I" + }, + "tnalloc": { + "n": "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC", + "s": "EJ9YoTJ81TcQ_pS9GmU2UbVURRm3ylnx_Wr1GbKjg0QP", + "o": "NI2I" + }, + "brandid": { + "n": "EAZz0-cvLBLfqw3TRo-J0kBzM1TEwQ6a_v_892uH3Yjz", + "s": "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z", + "o": "NI2I" } }, "r": { "d": "EMS9_VeDinkCdVlMVJKwbeBrsjnVj8VO1OS0walgg05X", + "governance": "Issued under governance published at https://provenant.net/governance/a2p-campaign/", "brandPrivacy": "Verifiers agree that, if they learn the identity of a brand as a sender of SMS messages by verifying this credential, they will not use this information to infer or model relationships between the brand and service providers.", "nonrepudiableBySig": "Senders of SMS messages agree that their reputation as a sender may be non-repudiably associated with messages that cite this campaign, exactly and only to the extent that the messages are signed by an entity cryptographically authorized to represent the brand." } -} \ No newline at end of file +} diff --git a/a2p-campaign/index.md b/a2p-campaign/index.md index 34403f0..864cebc 100644 --- a/a2p-campaign/index.md +++ b/a2p-campaign/index.md @@ -1,5 +1,41 @@ -## A2P Campaign Credentials +## A2P Campaign Credential ### Purpose -These credentials prove that a brand has been approved to run an A2P SMS campaign in US telecom contexts. \ No newline at end of file +A credential issued to an organization that represents a registered A2P messaging campaign and the telephone numbers associated with that campaign. + +### Schema + +See [a2p-campaign.schema.json](a2p-campaign.schema.json). + +### Attributes + +The attributes block records the approved campaign and sender context: + +| Field | Purpose | +|---|---| +| `brandId` | Legal or registry identifier for the approved organization. | +| `campaignId` | Campaign identifier assigned by the approval authority or registry. | +| `usecase` | Campaign use-case category, such as `Fraud Alert`, `2FA`, or `Public Service Announcement`. | +| `numbers` | E.164 numbers approved for use in the campaign. | +| `authorizedServiceProvider` | Service provider authorized to originate or manage traffic for this campaign. | +| `campaignAttributes` | Subscriber opt-in, opt-out, help, link, and affiliate-marketing attributes used by governance and verifiers. | + +The `startDate` and `endDate` fields are optional and can be used when the campaign approval is time-bounded. + +### Edge structure + +The `e` (edges) block may contain: + +| Edge | Purpose | +|---|---| +| `issuer` | Links to an identity credential proving who issued the campaign credential. | +| `tnalloc` | Links to a Telephone Number Allocation credential proving right to use the campaign telephone numbers. | +| `brandid` | Links to a brand or organization identity credential associated with the campaign. | + + +### Rules and governance + +The `r` (rules) block must contain: + +- `governance` - A statement identifying the governance framework under which this credential was issued. diff --git a/brand-owner/brand-owner.schema.json b/brand-owner/brand-owner.schema.json index bb504da..5ae607a 100644 --- a/brand-owner/brand-owner.schema.json +++ b/brand-owner/brand-owner.schema.json @@ -1,35 +1,68 @@ { - "$id": "EBpGNZSWwj-btOJMJSMLCVoXbtKdJTcggO-zMevr4vH_", - "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "EGNmJbfqUrgIi75YnTnyfZWJ15zRSvnStaxKZKH4_t4j", + "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Brand Owner Credential", "description": "Issued to a legal entity that has the right to use a brand because it is the direct owner or a licensee of that brand.", "type": "object", - "credentialType": "BrandOwnerCredential", - "version": "1.0.0", + "version": "2.0.0", + "required": [ + "v", + "d", + "i", + "ri", + "s", + "a", + "r" + ], "properties": { "v": { - "description": "Version", - "type": "string" + "description": "Version string using ACDC conventions, encoding protocol, serialization, and size.", + "type": "string", + "pattern": "^ACDC[0-9]{2}[A-Z]{4}[0-9a-f]{6}_$", + "examples": [ + "ACDC10JSON000345_" + ] }, "d": { - "description": "Credential SAID", - "type": "string" + "description": "SAID of the credential (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "u": { - "description": "One time use nonce", - "type": "string" + "description": "A salty nonce (high-entropy random value) used to prevent rainbow-table attacks on the credential SAID.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "Issuer AID", - "type": "string" + "description": "AID of the issuer (the party certifying the brand ownership right).", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EDC0Sj0CPYd70zUSY2ehvm7Z4kwZigugiA84wuS7lK2H", + "BCmx-dBiozRlK5MfRnznAHl9kmXjB3t-zxrE3hIIYkeS" + ] }, "ri": { - "description": "Credential status registry", - "type": "string" + "description": "SAID of the issuer's ACDC credential status registry.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EOkdwKgeEF-Ww2d61uhHjAo13rjJROdbdIaxORQJRV2G" + ] }, "s": { - "description": "Schema SAID", - "type": "string" + "description": "SAID of this schema (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z" + ] }, "a": { "oneOf": [ @@ -38,22 +71,46 @@ "type": "string" }, { - "$id": "EIDYFHkBOgNVWGFRcN1cEXNvRV47-nrNJGx6mKHBA7ia", + "$id": "EFdxGA7Kcx-1IfGZKd4pi8eUEKCp3by6MI7txirQpXOY", "description": "Attributes block", "type": "object", + "required": [ + "d", + "i", + "dt" + ], "properties": { "d": { - "description": "Attributes block SAID", - "type": "string" + "description": "SAID of the attributes block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EIDYFHkBOgNVWGFRcN1cEXNvRV47-nrNJGx6mKHBA7ia" + ] + }, + "u": { + "description": "A salty nonce for the attributes block, enabling selective disclosure.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "AID of the legal entity that is the direct owner or a licensee of the brand", - "type": "string" + "description": "AID of the legal entity that is the direct owner or licensee of the brand.", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EAZz0-cvLBLfqw3TRo-J0kBzM1TEwQ6a_v_892uH3Yjz" + ] }, "dt": { - "description": "Issuance date time", + "description": "Issuance date-time (when the ACDC was signed), as an ISO-8601 datetime string with timezone.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2024-01-15T10:30:00.000000+00:00" + ] }, "vcard": { "description": "An ordered list of unfolded, VCard content lines (properties) per RFC 6350, where property and parameter names are upper case, and parameter names appear in lexicographic order. Values that are telephone numbers MUST be in strict E164 format with a leading + but no other spaces or punctuation. The CHATBOT property is standard and is of type URI. If the type of a particular value is URI and refers to static media files (as, for example, with LOGO), the HASH parameter SHOULD be included and MUST be the CESR-encoded value of the content at the URI. Alternatively, data URIs MAY be used. A URI that refers to mutable content SHOULD NOT be used, as it is insecure; if present, the credential is asserting only the location, not the content of the logo.", @@ -89,11 +146,7 @@ } } }, - "additionalProperties": true, - "required": [ - "i", - "dt" - ] + "additionalProperties": true } ] }, @@ -101,37 +154,55 @@ "oneOf": [ { "description": "Edges block SAID", - "type": "string" + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" }, { - "$id": "EGt3Q1rQJweeryWfJGBYlKCFsYbNrYGYc6AaTRBzwzHG", + "$id": "EDQSHGWWUalHkh57IL-w05ie0JHefeij84T_hUkLDQLp", "description": "Edges detail", "type": "object", "required": [ - "d", - "issuer" + "d" ], "properties": { "d": { - "description": "Edges block SAID", - "type": "string" + "description": "SAID of the edges block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EGt3Q1rQJweeryWfJGBYlKCFsYbNrYGYc6AaTRBzwzHG" + ] }, "issuer": { - "description": "Edge credential that proves the identity of the issuer.", + "description": "Credential that proves the identity of the issuer.", "type": "object", "properties": { "n": { - "description": "SAID of a credential that proves the identity of the issuer", - "type": "string" + "description": "SAID of a credential that proves the identity of the issuer.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "s": { - "description": "SAID of credential schema that proves the identity of the issuer", - "type": "string" + "description": "SAID of the schema that the issuer identity credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9" + ] }, "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", "type": "string", - "const": "I2I" + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] } }, "additionalProperties": false, @@ -142,21 +213,35 @@ ] }, "brandauth": { - "description": "Edge credential that proves the brand authority.", + "description": "Credential that proves the brand authority (e.g., a trademark registration or license agreement).", "type": "object", "properties": { "n": { - "description": "SAID of a credential that proves the brand authority", - "type": "string" + "description": "SAID of a credential that proves the brand authority.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "s": { - "description": "SAID of credential schema that proves the brand authority", - "type": "string" + "description": "SAID of the schema that the brand authority credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z" + ] }, "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", "type": "string", - "const": "I2I" + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] } }, "additionalProperties": false, @@ -167,40 +252,43 @@ ] } }, - "additionalProperties": false + "additionalProperties": true } ] }, "r": { "oneOf": [ { - "description": "Rules section SAID", - "type": "string" + "description": "SAID of rules block (Blake3-256 digest in CESR compact encoding)", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" }, { - "$id": "EGFgHT7Xrzy9YLdQNXnNTYVBu9_Q0O7K5A2VCWjg93t3", + "$id": "EEr9mTJM4_VYvwg7rFql37vu5Y3Sb5kr346uzC6nesO7", "description": "Rules detail", "type": "object", "properties": { "d": { - "description": "Rule section SAID", - "type": "string" + "description": "SAID of the rules block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" + }, + "governance": { + "description": "Statement identifying the governance framework under which this credential was issued.", + "type": "string", + "examples": [ + "Issued under governance published at https://provenant.net/governance/brand-owner/" + ] } }, "additionalProperties": true, "required": [ - "d" + "d", + "governance" ] } ] } }, - "additionalProperties": false, - "required": [ - "i", - "ri", - "s", - "d", - "r" - ] + "additionalProperties": false } \ No newline at end of file diff --git a/brand-owner/index.md b/brand-owner/index.md index 404e4e2..81907ef 100644 --- a/brand-owner/index.md +++ b/brand-owner/index.md @@ -1,5 +1,79 @@ -## Brand Owner Credentials +## Brand Owner Credential -#### Purpose +### Purpose -These credentials document the issuee's right to use certain elements of a brand, either because the brand is owned by the issuee, or because it is licensed to them. \ No newline at end of file +This credential is issued to a legal entity that has the **right to use a brand** because it is either the direct owner of the brand or a licensee authorized to act under it. It establishes that a specific organization is the legitimate operator of a brand identity — including its name, logo, contact information, and communications channels. + +In voice and messaging ecosystems, the Brand Owner Credential is the mechanism by which a verifier can answer the question: *"Is this call or message legitimately coming from the organization it claims to represent?"* By chaining the brand credential back to both an identity credential (proving the legal entity exists) and a brand authority credential (proving the right to use the brand), a verifier gets cryptographic assurance that the brand presentation is authentic. + +### Schema + +See [brand-owner.schema.json](brand-owner.schema.json). + +### Required and optional attributes + +The attributes block requires `d` (attributes SAID), `i` (issuee AID), and `dt` (issuance datetime). `vcard` and `goals` are both optional, though in practice a brand owner credential without a `vcard` is of limited use. Both fields may be selectively disclosed. + +### Brand attributes (`vcard`) + +The `vcard` field is an ordered array of unfolded VCard content lines (RFC 6350). This is the canonical representation of the brand's identity — the information a verifier would present to a call recipient or SMS recipient to describe who is contacting them. + +Key conventions: + +- Property and parameter names are **upper case**. +- Parameter names appear in **lexicographic order**. +- Telephone number values MUST be in **strict E.164 format** (leading `+`, no spaces or punctuation). +- The `CHATBOT` property is standard and takes a URI value. +- For `LOGO` and other static media URIs, the `HASH` parameter SHOULD be included and MUST be the CESR-encoded Blake3-256 digest of the content at the URI. This prevents a logo from being silently swapped after issuance. Alternatively, a data URI may be used to embed the media directly. +- URIs pointing to mutable content SHOULD NOT be used — if present, the credential asserts only the location, not the content. + +Example vcard entries: + +``` +ORG:Acme Space Travel, Ltd. +NICKNAME:Acme Rockets +CHATBOT:https://acmespacetravel.biz/chat +LOGO;HASH=EK2r6EnDXre2pecTBO8s99j4OtNaaDIhVyr7uGugDhmp;VALUE=URI:https://acmespacetravel.biz/logo64x48.png +TEL;TYPE=support:+14155550199 +EMAIL:support@acmespacetravel.biz +URL:https://www.acmespacetravel.biz +ADR;TYPE=work:;;1 Rocket Road;Hawthorne;CA;90250;United States +TZ:America/Los_Angeles +LANG:en-US +``` + +### Goal codes (`goals`) + +The optional `goals` field lists [Hyperledger Aries goal codes](https://bit.ly/49V8YqV) that enumerate the formally-defined activities in which this brand may legitimately engage using the asserted brand attributes. If specified, any activity **not** covered by these goal codes is considered a context in which legitimate use of the brand is not asserted by this credential. + +This field is the primary mechanism for **constraining channel and purpose**. For example: +- A brand that only does outbound voice calls would include goal codes for voice. +- A brand that only does A2P SMS marketing would include goal codes for SMS campaigns. +- A brand operating in both channels would include goal codes for both. + +This allows a single Brand Owner Credential to serve multiple channels without schema proliferation. + +### Edge structure + +The `e` (edges) block is optional. When present, it may contain: + +| Edge | Required in block? | Purpose | +|---|---|---| +| `issuer` | No | Links to an identity credential (e.g., Org Identity, vLEI) proving the identity of the issuer. Defaults to `I2I` operator. | +| `brandauth` | No | Links to a credential proving brand authority — e.g., a trademark registration or license agreement. Defaults to `I2I` operator. | + +### Multichannel readiness + +A single Brand Owner Credential is designed to work across voice, SMS, and other channels. The `vcard` field captures the brand's full contact profile; the `goals` field constrains which channels and activities the credential covers. This avoids the need for separate brand credentials per channel. + +If a brand's voice and SMS operations have materially different contact information (e.g., different numbers or chatbot endpoints), separate credentials can be issued — but in the common case, one credential is sufficient. + +### Rules and governance + +The `r` (rules) block must contain: + +- **`governance`** — A statement identifying the governance framework under which this credential was issued. Issuers must populate this field with the URI of their applicable governance document. + +Additional rules may be present and are governed by the issuer's governance framework. + +The act of issuing or accepting this credential constitutes binding acceptance of those rules. diff --git a/brand-owner/rules.json b/brand-owner/rules.json deleted file mode 100644 index 3de7fd4..0000000 --- a/brand-owner/rules.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "d": "EJFhpp0uU7D7PKooYM5QIO1hhPKTjHE18sR4Dn0GFscR", - "perBrand": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." -} \ No newline at end of file diff --git a/dossier-base/dossier-base.json b/dossier-base/dossier-base.schema.json similarity index 99% rename from dossier-base/dossier-base.json rename to dossier-base/dossier-base.schema.json index ae04ba7..7756c41 100644 --- a/dossier-base/dossier-base.json +++ b/dossier-base/dossier-base.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "ECqmlipYuqp8LA_7WdZGt_cKP9eK3hXtHRZGNgJ7NKEx", + "$id": "EHxI61CGs7FRuStz8P6QWJyMK4u2bGH1LQqIXsA4bT7q", "title": "Dossier Base Schema", "description": "Base schema defining the canonical structure of a Dossier ACDC. A schema S IS-A dossier iff S's top-level allOf array contains a $ref to this schema's SAID, or recursively to another schema that IS-A dossier. A dossier SHOULD NOT include an issuee; all evidence MUST be carried in e, never in a.", "type": "object", diff --git a/org-identity/index.md b/org-identity/index.md new file mode 100644 index 0000000..ad926e8 --- /dev/null +++ b/org-identity/index.md @@ -0,0 +1,85 @@ +## Org Identity Credential + +### Purpose + +This credential **connects different identifiers for the same organization**, binding legal entity identity to a cryptographic identifier (AID). It is issued to an AID that is provably controlled by the named legal entity, allowing verifiers to confirm that the AID belongs to a real, legally-recognized organization. + +This is the foundational trust anchor for the OVC ecosystem. Brand owner credentials, telephone number allocation credentials, and campaign credentials all trace back to an org identity credential as proof that the parties involved are real, accountable legal entities — not anonymous actors. + +The Org Identity Credential is analogous in intent to the [LE vLEI](https://docs.origincloud.net/start/concepts/creds/vleis) defined by GLEIF (which maps to LoA 3), but its schema is designed to be simpler and to accommodate a wider range of national registry sources. + +![suggested org identity visual](org-identity-256.png)
+Suggested visual: [svg](org-identity.svg) | [256 px](org-identity-256.png) | [128 px](org-identity-128.png) | [64 px](org-identity-64.png) | [32 px](org-identity-32.png) + +### Levels of assurance + +Levels of assurance (LoAs) are well known and often referenced for individual identity; they are less adopted in organizational identity. In the United States, the FBCA [defines](https://www.idmanagement.gov/docs/fbca-cp.pdf) *basic*, *medium*, and *high* assurance for certificates issued to federal agencies, but these LoAs are not typically referenced in other contexts. In the EU, eIDAS ([EU regulation 910/2014](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32014R0910), article 28) defines "nonqualified" and "qualified/QSeal" assurance for certificate issuance — but its rollout is young, and its application for non-certificate-based technologies is unclear. + +Org identity credentials convey a level of assurance with a positive number, where larger numbers map to higher levels of assurance (1 < 2 < 3). Normally, these numbers are expected to be integers, but nuances within a given integer can be modeled by using a floating point value instead (2.1 < 2.2). This allows verifiers to decide what level of assurance will satisfy them, and accept any credential having an LoA >= their threshhold. The meaning of the integer values are defined as follows: + +LoA | intended meaning | verification procedures | mappings +--- | --- | --- | --- +1 aka "bronze"| basic proof of control + authorization of requester; no claim about legalities, tools, governance, tools, or competence |
  1. Prove that a non-cryptographic identifier (e.g., an LEI) references an org that exists and is not defunct.
  2. Prove org owns domain.
  3. Prove requester is human and has email in domain.
  4. Prove requester has modified a DNS record for the domain to claim the issue's cryptographic identifier (AID).
| Similar to FBAC "basic" or eIDAS "nonqual". +2 aka "silver"| cryptographic proof of control + authz, legal accountability, tools; no claim about governance or competence |
  1. Satisfy requirements for LoA 1.
  2. Prove the legal identity of the requester via a digital credential having eIDAS *substantial* assurance, or use a physical credential that meets ISO/IEC 2915 LoA2 or NIST IAL2 requirements.
  3. Prove cryptographically (e.g., using a [GCD credential](../gcd/index.md) and/or a KERI delegated AID) that the requester was authorized by the org to request a credential for it.
  4. Use at least 1 witness for the org's AID.
| Similar to FBAC "medium", X509 extended verification, or eIDAS nonqual with deep vet. However, not a perfect analog; we are proving that the org has the tools to maintain their identity for a long time. +3 aka "gold" |
  1. Satisfy requirements for LoA 2.
  2. Prove that the requester has legal signing authority for the org.
    3. Prove that the org has a multisig signing committee to manage risk and human turnover.
  3. Issue the credential in a ceremony where it is proved that there is no MITM between any two members of the signing committee, and between each member of the signing committee and at least one external observer.
  4. Require that the AID of the org use enough witnesses to reliably detect and recover from duplicity.
| This approximates FBAC "high" and eIDAS "QSeal", but goes slightly beyond. It maps directly to the LE vLEI defined by GLEIF. +4 aka "platinum" | TBD, but could require use of hardware security and/or proof of specialized org attributes such as a security clearance. | none + + + + +### Schema + +See [org-identity.schema.json](org-identity.schema.json). + +### Legal identifiers (`legalIdentifiers`) + +The `legalIdentifiers` field lists the external identifiers the vetter used to confirm the organization's existence and attributes at the time of issuance. Each entry has a `type` (the registry or source) and a `value` (the identifier within that registry). + +**At least one identifier should be globally unambiguous and portable across jurisdictions** — typically an LEI. National registry IDs (like UK Companies House `uk-crn` or Swiss `che` numbers) are also valid and can coexist with the LEI. + +Domain names and social media handles are intentionally excluded: they do not unambiguously identify a legal entity across jurisdictions. + +Examples of valid types: + +| type | example value | source | +|---|---|---| +| `lei` | `5493001KJTIIGC8Y1R12` | GLEIF (ISO 17442) | +| `uk-crn` | `01234567` | UK Companies House | +| `che` | `CHE-123.456.789` | Swiss UID Register | +| `us-ein` | `12-3456789` | US IRS EIN | +| `duns` | `123456789` | Dun & Bradstreet | +| `edgar` | `0001234567` | US SEC EDGAR | + +### Levels of Assurance (`LOA`) + +The `LOA` field is a positive number where larger values denote higher assurance. Integer values represent defined tiers; decimal sub-values (e.g., 2.1) allow nuance within a tier. Verifiers should accept any credential where `LOA >= their required threshold`. + +| LOA | Informal name | Intended meaning | +|---|---|---| +| 1 | Bronze | Basic proof of control + authorization of requester; no claim about legalities, tools, or governance. | +| 2 | Silver | Cryptographic proof of control + legal accountability and tooling; no claim about governance or competence. | +| 3 | Gold | Full legal signing authority proven; multisig signing committee; ceremony with no MITM. Equivalent to LE vLEI (GLEIF). | +| 4 | Platinum | TBD — reserved for hardware security or specialized org attributes (e.g., security clearance). | + +### Edge structure + +The `e` (edges) block is optional. When present, it may contain: + +| Edge | Required in block? | Purpose | +|---|---|---| +| `issuer` | No | Links to an identity credential proving the identity of the issuing vetter. Uses `I2I` operator — the issuer AID of this credential must be the issuee AID of the referenced credential. | + +### Rules and governance + +The `r` (rules) block uses citation-style rules inherited from the credential design: the listed legal identifiers are citations — they point to external registry records. When the rules block is expanded (object form), it MUST contain `governance` and MAY include: + +- `onlyCommitToPoint` — Pointing to an identifier does **not** imply endorsement of or agreement with the cited content. +- `useViaEdges` — The credential is not meant to be used in isolation; its semantics are communicated via referencing ACDCs. +- `undefinedVerification` — Verifying the authenticity of the cited external data is the verifier's responsibility. +- `undefinedRevocation` — Revocation of the credential and revocation of the cited data are independent events. +- `governance` — Identifies the governance framework under which the credential was issued. + +### Multichannel readiness + +This credential is entirely channel-agnostic. It asserts the legal identity of an organization, regardless of how that organization communicates (voice, SMS, web, etc.). It is a building block used by channel-specific credentials, not a channel-specific credential itself. + diff --git a/org-vet/org-vet-128.png b/org-identity/org-identity-128.png similarity index 100% rename from org-vet/org-vet-128.png rename to org-identity/org-identity-128.png diff --git a/org-vet/org-vet-256.png b/org-identity/org-identity-256.png similarity index 100% rename from org-vet/org-vet-256.png rename to org-identity/org-identity-256.png diff --git a/org-vet/org-vet-32.png b/org-identity/org-identity-32.png similarity index 100% rename from org-vet/org-vet-32.png rename to org-identity/org-identity-32.png diff --git a/org-vet/org-vet-64.png b/org-identity/org-identity-64.png similarity index 100% rename from org-vet/org-vet-64.png rename to org-identity/org-identity-64.png diff --git a/org-identity/org-identity.schema.json b/org-identity/org-identity.schema.json new file mode 100644 index 0000000..723f532 --- /dev/null +++ b/org-identity/org-identity.schema.json @@ -0,0 +1,298 @@ +{ + "$id": "EBCa5bot0IhTiuSD_jK4hjS4j9WsD2cocu8UXrG67Odi", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Org Identity Credential", + "description": "Connects different identifiers for the same organization, binding legal entity identity to a cryptographic identifier.", + "type": "object", + "version": "2.0.0", + "required": [ + "v", + "d", + "i", + "ri", + "s", + "a", + "r" + ], + "properties": { + "v": { + "description": "Version string using ACDC conventions, encoding protocol, serialization, and size.", + "type": "string", + "pattern": "^ACDC[0-9]{2}[A-Z]{4}[0-9a-f]{6}_$", + "examples": [ + "ACDC10JSON000345_" + ] + }, + "d": { + "description": "SAID of the credential (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] + }, + "u": { + "description": "A salty nonce (high-entropy random value) used to prevent rainbow-table attacks on the credential SAID.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] + }, + "i": { + "description": "AID of the issuer (the party asserting the org identity vetting).", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EDC0Sj0CPYd70zUSY2ehvm7Z4kwZigugiA84wuS7lK2H", + "BCmx-dBiozRlK5MfRnznAHl9kmXjB3t-zxrE3hIIYkeS" + ] + }, + "ri": { + "description": "SAID of the issuer's ACDC credential status registry.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EOkdwKgeEF-Ww2d61uhHjAo13rjJROdbdIaxORQJRV2G" + ] + }, + "s": { + "description": "SAID of this schema (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9" + ] + }, + "a": { + "oneOf": [ + { + "description": "Attributes block SAID", + "type": "string" + }, + { + "$id": "EGq0lw7-4-wkz5m3ZvOgHMm1HLuKIo7NcUZM93FYsLFK", + "description": "Attributes block", + "type": "object", + "required": [ + "d", + "i", + "dt" + ], + "properties": { + "d": { + "description": "SAID of the attributes block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ELtdYgSHM9VElQtjd4P19IB24HH8PQZGbEctOjmP69QE" + ] + }, + "u": { + "description": "A salty nonce for the attributes block, enabling selective disclosure.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] + }, + "i": { + "description": "AID of the legal entity (issuee) whose identity was vetted.", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EAZz0-cvLBLfqw3TRo-J0kBzM1TEwQ6a_v_892uH3Yjz" + ] + }, + "dt": { + "description": "Issuance date-time (when the ACDC was signed), as an ISO-8601 datetime string with timezone.", + "type": "string", + "format": "date-time", + "examples": [ + "2024-01-15T10:30:00.000000+00:00" + ] + }, + "LOA": { + "description": "Level of Assurance \u2014 a positive number where larger values denote higher assurance (1=bronze, 2=silver, 3=gold). Integer values represent defined tiers; decimal sub-values (e.g., 2.1) allow nuance within a tier. Verifiers should accept any credential where LOA is >= their required threshold.", + "type": "number", + "exclusiveMinimum": 0, + "examples": [ + 1, + 2, + 3 + ] + }, + "LEI": { + "description": "Legal Entity Identifier (LEI) \u2014 a globally unique 20-character alphanumeric code conforming to ISO 17442.", + "type": "string", + "pattern": "^[A-Z0-9]{20}$", + "examples": [ + "5493001KJTIIGC8Y1R12" + ] + }, + "legalIdentifiers": { + "description": "Array of legal identifiers associated with this organization, as referenced during vetting. Each item has a type and value, making the identity source explicit. Sources may include national registries, OpenCorporates, EDGAR, Dun & Bradstreet, or a stock exchange. At least one identifier should be globally unambiguous and portable across jurisdictions.", + "type": "array", + "uniqueItems": true, + "minItems": 1, + "items": { + "type": "object", + "properties": { + "type": { + "description": "Category or source of the identifier (e.g., lei, us-ein, uk-crn, che, duns, edgar, etc.)", + "type": "string" + }, + "value": { + "description": "The identifier value", + "type": "string" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": true, + "examples": [ + { + "type": "lei", + "value": "5493001KJTIIGC8Y1R12" + }, + { + "type": "uk-crn", + "value": "01234567" + }, + { + "type": "che", + "value": "CHE-123.456.789" + }, + { + "type": "us-ein", + "value": "12-3456789" + } + ] + } + } + }, + "additionalProperties": true + } + ] + }, + "r": { + "oneOf": [ + { + "description": "SAID of rules block (Blake3-256 digest in CESR compact encoding)", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" + }, + { + "$id": "EJ6JvJ5LprzI_WdtyZ1BUlk7GmL1tRw538a5MZzpiwnK", + "description": "Rules detail", + "type": "object", + "required": [ + "d", + "governance" + ], + "properties": { + "d": { + "description": "SAID of the rules block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" + }, + "governance": { + "description": "Statement identifying the governance framework under which this credential was issued.", + "type": "string", + "examples": [ + "Issued under governance published at https://provenant.net/governance/org-identity/" + ] + }, + "onlyCommitToPoint": { + "description": "All parties agree that the citation, in and of itself, only commits the issuer to point at content in a way that makes the issuer and the target verifiable. Unless or until context, governance, or other actions prove intent, the citation does NOT imply that the issuer owns, endorses, or agrees with the content.", + "type": "string" + }, + "useViaEdges": { + "description": "All parties acknowledge that the citation is not intended to be used in isolation. Rather, the intended semantics for the citation should be communicated via a referencing ACDC that clarifies its issuer's intention.", + "type": "string" + }, + "undefinedVerification": { + "description": "All parties agree that procedures for evaluating the authenticity and/or veracity of the referenced content are beyond the scope of standard ACDC verification, and that the verifier is responsible for evaluating in whatever way satisfies their requirements.", + "type": "string" + }, + "undefinedRevocation": { + "description": "Unless or until governance specifies otherwise, all parties agree that there is no defined relationship between the revocation status of a citation and that of cited data. Cited data may be disavowed or revoked by its creator without a citation being revoked, and vice versa.", + "type": "string" + } + }, + "additionalProperties": true + } + ] + }, + "e": { + "oneOf": [ + { + "description": "Edges block SAID", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" + }, + { + "$id": "EJ3MEBe2jXRjw0IFI71APybcd-Apufu7TRZYE9bFLM-Q", + "description": "Edges detail", + "type": "object", + "required": [ + "d" + ], + "properties": { + "d": { + "description": "SAID of the edges block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EKk5ejftEjNwjRhw2lYQAwKwvRWapqCNEOx3gUR7WW7n" + ] + }, + "issuer": { + "description": "Credential that proves the identity of the issuer.", + "type": "object", + "properties": { + "n": { + "description": "SAID of a credential that proves the identity of the issuer.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] + }, + "s": { + "description": "SAID of the schema that the issuer identity credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9" + ] + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false, + "required": [ + "n", + "s", + "o" + ] + } + }, + "additionalProperties": true + } + ] + } + }, + "additionalProperties": false +} \ No newline at end of file diff --git a/org-vet/org-vet.svg b/org-identity/org-identity.svg similarity index 100% rename from org-vet/org-vet.svg rename to org-identity/org-identity.svg diff --git a/org-vet/index.md b/org-vet/index.md deleted file mode 100644 index 863f55a..0000000 --- a/org-vet/index.md +++ /dev/null @@ -1,33 +0,0 @@ -## Org Vet Credentials - -### Purpose - -This credential asserts with an explicit level of assurance the existence and attributes of an organization. It is issued to a cryptographic identifier controlled by the org, allowing the org to authenticate itself on the basis of the credential. (The [LE vLEI](https://docs.origincloud.net/start/concepts/creds/vleis) is essentially an org vet credential at LoA 3, but its schema varies slightly to express some GLEIF governance requirements.) - -![suggested org vet visual](org-vet-256.png)
-Suggested visual: [svg](org-vet.svg) | [256 px](org-vet-256.png) | [128 px](org-vet-128.png) | [64 px](org-vet-64.png) | [32 px](org-vet-32.png) - -### Levels of assurance - -Levels of assurance (LoAs) are well known and often referenced for individual identity; they are less adopted in organizational identity. In the United States, the FBCA [defines](https://www.idmanagement.gov/docs/fbca-cp.pdf) *basic*, *medium*, and *high* assurance for certificates issued to federal agencies, but these LoAs are not typically referenced in other contexts. In the EU, eIDAS ([EU regulation 910/2014](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32014R0910), article 28) defines "nonqualified" and "qualified/QSeal" assurance for certificate issuance — but its rollout is young, and its application for non-certificate-based technologies is unclear. - -Org vet credentials convey a level of assurance with a positive number, where larger numbers map to higher levels of assurance (1 < 2 < 3). Normally, these numbers are expected to be integers, but nuances within a given integer can be modeled by using a floating point value instead (2.1 < 2.2). This allows verifiers to decide what level of assurance will satisfy them, and accept any credential having an LoA >= their threshhold. The meaning of the integer values are defined as follows: - -LoA | intended meaning | verification procedures | mappings ---- | --- | --- | --- -1 aka "bronze"| basic proof of control + authorization of requester; no claim about legalities, tools, governance, tools, or competence |
  1. Prove that a non-cryptographic identifier (e.g., an LEI) references an org that exists and is not defunct.
  2. Prove org owns domain.
  3. Prove requester is human and has email in domain.
  4. Prove requester has modified a DNS record for the domain to claim the issue's cryptographic identifier (AID).
| Similar to FBAC "basic" or eIDAS "nonqual". -2 aka "silver"| cryptographic proof of control + authz, legal accountability, tools; no claim about governance or competence |
  1. Satisfy requirements for LoA 1.
  2. Prove the legal identity of the requester via a digital credential having eIDAS *substantial* assurance, or use a physical credential that meets ISO/IEC 2915 LoA2 or NIST IAL2 requirements.
  3. Prove cryptographically (e.g., using a [GCD credential](../gcd/index.md) and/or a KERI delegated AID) that the requester was authorized by the org to request a credential for it.
  4. Use at least 1 witness for the org's AID.
| Similar to FBAC "medium", X509 extended verification, or eIDAS nonqual with deep vet. However, not a perfect analog; we are proving that the org has the tools to maintain their identity for a long time. -3 aka "gold" |
  1. Satisfy requirements for LoA 2.
  2. Prove that the requester has legal signing authority for the org.
    3. Prove that the org has a multisig signing committee to manage risk and human turnover.
  3. Issue the credential in a ceremony where it is proved that there is no MITM between any two members of the signing committee, and between each member of the signing committee and at least one external observer.
  4. Require that the AID of the org use enough witnesses to reliably detect and recover from duplicity.
| This approximates FBAC "high" and eIDAS "QSeal", but goes slightly beyond. It maps directly to the LE vLEI defined by GLEIF. -4 aka "platinum" | TBD, but could require use of hardware security and/or proof of specialized org attributes such as a security clearance. | none - - - - -### Schema - -See [org-vet.schema.json](org-vet.schema.json) and also [rules.json](rules.json). - -### Governance Framework - -These credentials are governed by rules to enhance assurance, discourage abuse, and keep use cases crisp. The current rules are stated in [rules.json](rules.json) and are identified by SAID `EFthNcTE20MLMaCOoXlSmNtdooGEbZF8uGmO5G85eMSF`. New governance frameworks can be written that supplement these rules; see the `gfw` field in the schema. It is also possible to modify or override these rules, by placing a different value in the `r` field. The act of issuing or receiving a GCD credential constitutes binding acceptance of the rules. - diff --git a/org-vet/org-vet.schema.json b/org-vet/org-vet.schema.json deleted file mode 100644 index 82518c8..0000000 --- a/org-vet/org-vet.schema.json +++ /dev/null @@ -1,137 +0,0 @@ -{ - "$id": "EJvwY9n7EsJ4ZejUBHFrnrNammC8BkGI9YaW1Wnp5c22", - "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Org Vet", - "description": "Authenticate an org with an explicit level of assurance.", - "type": "object", - "credentialType": "orgVet", - "version": "1.0.0", - "required": [ - "v", - "d", - "i", - "ri", - "s", - "a", - "r" - ], - "properties": { - "v": { - "description": "Version string using ACDC conventions", - "type": "string" - }, - "d": { - "description": "SAID of the credential", - "type": "string" - }, - "i": { - "description": "Identifier of the issuer", - "type": "string" - }, - "ri": { - "description": "Issuer's ACDC status registry", - "type": "string" - }, - "s": { - "description": "SAID of this schema", - "type": "string" - }, - "a": { - "$id": "ELtdYgSHM9VElQtjd4P19IB24HH8PQZGbEctOjmP69QE", - "description": "Attributes block", - "type": "object", - "required": [ - "d", - "dt" - ], - "properties": { - "d": { - "description": "SAID of attributes block", - "type": "string" - }, - "dt": { - "description": "Issuance date (when the ACDC was signed).", - "format": "date-time", - "type": "string" - }, - "loa": { - "description": "Level of assurance.", - "type": "number" - }, - "lids": { - "description": "Array of linked identifiers (LIDs) that vetter claims were able to act as references for this legal entity when the org was vetted. At least one item in this list should be globally unambigious and portable across jurisdictions (e.g., an LEI). Others may come from national registries, OpenCorporates, EDGAR, Dun & Bradstreet, a stock exchange, a LinkedIn profile, a social media handle, a domain name, etc. The nature of individual item is detectable by regex match.", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "examples": [ - "5493001KJTIIGC8Y1R12", - "gb/01234567", - "CHE-123.456.789", - "12-345-6789", - "acmespacetravel.biz" - ], - "type": "string" - } - } - }, - "additionalProperties": true - }, - "r": { - "description": "SAID of rules block", - "type": "string", - "const": "EM6kWxMNL9BFm0ReegqQfNJLw8OZAfn2ZxcjWs4Ceifh", - "format": "cesr" - }, - "e": { - "oneOf": [ - { - "description": "Edges block SAID", - "type": "string" - }, - { - "$id": "EKk5ejftEjNwjRhw2lYQAwKwvRWapqCNEOx3gUR7WW7n", - "description": "Edges detail", - "type": "object", - "required": [ - "d", - "issuer" - ], - "properties": { - "d": { - "description": "Edges block SAID", - "type": "string" - }, - "issuer": { - "description": "Edge credential that proves the identity of the issuer.", - "type": "object", - "properties": { - "n": { - "description": "SAID of a credential that proves the identity of the issuer", - "type": "string" - }, - "s": { - "description": "SAID of credential schema that proves the identity of the issuer", - "type": "string" - }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" - } - }, - "additionalProperties": false, - "required": [ - "n", - "s", - "o" - ] - } - }, - "additionalProperties": false - } - ] - } - }, - "additionalProperties": true -} \ No newline at end of file diff --git a/org-vet/rules.json b/org-vet/rules.json deleted file mode 100644 index 135f063..0000000 --- a/org-vet/rules.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "d": "EM6kWxMNL9BFm0ReegqQfNJLw8OZAfn2ZxcjWs4Ceifh", - "onlyCommitToPoint": "All parties agree that the citation, in and of itself, only commits the issuer to point at content in a way that makes the issuer and the target verifiable. Unless or until context, governance, or other actions prove intent, the citation does NOT imply that the issuer owns, endorses, or agrees with the content.", - "useViaEdges": "All parties acknowledge that the citation is not intended to be used in isolation. Rather, the intended semantics for the citation should be communicated via a referencing ACDC that clarifies its issuer's intention.", - "undefinedVerification": "All parties agree that procedures for evaluating the authenticity and/or veracity of the referenced content are beyond the scope of standard ACDC verification, and that the verifier is responsible for evaluating in whatever way satisfies their requirements.", - "undefinedRevocation": "Unless or until governance specifies otherwise, all parties agree that there is no defined relationship between the revocation status of a citation and that of cited data. Cited data may be disavowed or revoked by its creator without a citation being revoked, and vice versa." -} \ No newline at end of file diff --git a/ovc-brand-owner/example-ovc-brand-owner.json b/ovc-brand-owner/example-ovc-brand-owner.json deleted file mode 100644 index 2d3c9d6..0000000 --- a/ovc-brand-owner/example-ovc-brand-owner.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "d": "EHWEdU7GMOOQZlhjtGaV_5689WmfWIu4C5gc9Iy7Tw2H", - "v": "ACDC10JSON00011c_", - "s": "EKUPqIZ1irc7FjYBMYMvELPfZ-4qSQyLjOrkP0RWB9Wh", - "i": "Ez6QKIKLzrGqpq4v9Bj908pQanoRKwOgBXjPW-w-P_8Q", - "ri": "EiySMSMLRrpt9AD_b34VEtUD6tDO0yaGoWCwB1iyJOgY", - "a": { - "d": "EMICXupK5CUxj5QuItQ8GV-QNV7lWQZpaRqUxnNeU_0H", - "i": "EK2r6EnDXre2pecTBO8s99j4OtNaaDIhVyr7uGugDhmp", - "dt": "2024-11-01T14:23:16+00:00", - "numbers": ["+18013612446"], - "channel": "sms", - "doNotOriginate": false, - "startDate": "2024-11-13T20:20:39+00:00", - "endDate": "2024-12-13T20:20:39+00:00" - }, - "r": "EJFhpp0uU7D7PKooYM5QIO1hhPKTjHE18sR4Dn0GFscR", - "e": { - "d": "EOS9BUu6iHS6QaTADgHWcWG36tsKYY3g_z3nCkrnbBMr", - "le": { - "n": "EOy_g1RrcQW_uh63l9SH7TGflNefu3Pe2C3asw_H2CFv", - "s": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" - } - } -} \ No newline at end of file diff --git a/ovc-brand-owner/index.md b/ovc-brand-owner/index.md deleted file mode 100644 index 404e4e2..0000000 --- a/ovc-brand-owner/index.md +++ /dev/null @@ -1,5 +0,0 @@ -## Brand Owner Credentials - -#### Purpose - -These credentials document the issuee's right to use certain elements of a brand, either because the brand is owned by the issuee, or because it is licensed to them. \ No newline at end of file diff --git a/ovc-brand-owner/ovc-brand-owner.schema.json b/ovc-brand-owner/ovc-brand-owner.schema.json deleted file mode 100644 index 1f168bd..0000000 --- a/ovc-brand-owner/ovc-brand-owner.schema.json +++ /dev/null @@ -1,206 +0,0 @@ -{ - "$id": "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "OVC Brand Owner Credential", - "description": "Issued to a legal entity that has the right to use a brand because it is the direct owner or a licensee of that brand.", - "type": "object", - "credentialType": "BrandOwnerCredential", - "version": "1.0.0", - "properties": { - "v": { - "description": "Version", - "type": "string" - }, - "d": { - "description": "Credential SAID", - "type": "string" - }, - "u": { - "description": "One time use nonce", - "type": "string" - }, - "i": { - "description": "Issuer AID", - "type": "string" - }, - "ri": { - "description": "Credential status registry", - "type": "string" - }, - "s": { - "description": "Schema SAID", - "type": "string" - }, - "a": { - "oneOf": [ - { - "description": "Attributes block SAID", - "type": "string" - }, - { - "$id": "EIDYFHkBOgNVWGFRcN1cEXNvRV47-nrNJGx6mKHBA7ia", - "description": "Attributes block", - "type": "object", - "properties": { - "d": { - "description": "Attributes block SAID", - "type": "string" - }, - "i": { - "description": "AID of the legal entity that is the direct owner or a licensee of the brand", - "type": "string" - }, - "dt": { - "description": "Issuance date time", - "format": "date-time", - "type": "string" - }, - "vcard": { - "description": "An ordered list of unfolded, VCard content lines (properties) per RFC 6350, where property and parameter names are upper case, and parameter names appear in lexicographic order. Values that are telephone numbers MUST be in strict E164 format with a leading + but no other spaces or punctuation. The CHATBOT property is standard and is of type URI. If the type of a particular value is URI and refers to static media files (as, for example, with LOGO), the HASH parameter SHOULD be included and MUST be the CESR-encoded value of the content at the URI. Alternatively, data URIs MAY be used. A URI that refers to mutable content SHOULD NOT be used, as it is insecure; if present, the credential is asserting only the location, not the content of the logo.", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "format": "cesr", - "type": "string" - }, - "examples": [ - "ORG:Example Company UK, Ltd", - "NICKNAME:Examples-R-Us", - "CHATBOT:https://example.com/chatwithus", - "LOGO;HASH=EK2r6EnDXre2pecTBO8s99j4OtNaaDIhVyr7uGugDhmp;VALUE=URI:https://example.com/logo64x48.png", - "TEL;TYPE=support:+445555555555", - "EMAIL:support@example.com", - "URL:https://www.example.com", - "ADR;TYPE=work:;;123 Example Street;London;;SW1A 1AA;United Kingdom", - "GEO:51.5074;-0.1278", - "TZ:Europe/London", - "LANG:en-GB" - ] - }, - "goals": { - "description": "Goal codes (see https://bit.ly/49V8YqV) that enumerate formally-defined activities in which the brand's owner might engage using the asserted brand attributes. If specified, activities not covered by these goal codes are considered contexts in which the legitimate use of the brand is not asserted by this credential.", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "format": "cesr", - "type": "string" - } - } - }, - "additionalProperties": true, - "required": [ - "i", - "dt" - ] - } - ] - }, - "e": { - "oneOf": [ - { - "description": "Edges block SAID", - "type": "string" - }, - { - "$id": "EGt3Q1rQJweeryWfJGBYlKCFsYbNrYGYc6AaTRBzwzHG", - "description": "Edges detail", - "type": "object", - "required": [ - "d", - "issuer" - ], - "properties": { - "d": { - "description": "Edges block SAID", - "type": "string" - }, - "issuer": { - "description": "Edge credential that proves the identity of the issuer.", - "type": "object", - "properties": { - "n": { - "description": "SAID of a credential that proves the identity of the issuer", - "type": "string" - }, - "s": { - "description": "SAID of credential schema that proves the identity of the issuer", - "type": "string" - }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" - } - }, - "additionalProperties": false, - "required": [ - "n", - "s", - "o" - ] - }, - "brandauth": { - "description": "Edge credential that proves the brand authority.", - "type": "object", - "properties": { - "n": { - "description": "SAID of a credential that proves the brand authority", - "type": "string" - }, - "s": { - "description": "SAID of credential schema that proves the brand authority", - "type": "string" - }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" - } - }, - "additionalProperties": false, - "required": [ - "n", - "s", - "o" - ] - } - }, - "additionalProperties": false - } - ] - }, - "r": { - "oneOf": [ - { - "description": "Rules section SAID", - "type": "string" - }, - { - "$id": "EGFgHT7Xrzy9YLdQNXnNTYVBu9_Q0O7K5A2VCWjg93t3", - "description": "Rules detail", - "type": "object", - "properties": { - "d": { - "description": "Rule section SAID", - "type": "string" - } - }, - "additionalProperties": true, - "required": [ - "d" - ] - } - ] - } - }, - "additionalProperties": false, - "required": [ - "i", - "ri", - "s", - "d", - "r" - ] -} \ No newline at end of file diff --git a/ovc-brand-owner/rules.json b/ovc-brand-owner/rules.json deleted file mode 100644 index 3de7fd4..0000000 --- a/ovc-brand-owner/rules.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "d": "EJFhpp0uU7D7PKooYM5QIO1hhPKTjHE18sR4Dn0GFscR", - "perBrand": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." -} \ No newline at end of file diff --git a/ovc-org-vet/index.md b/ovc-org-vet/index.md deleted file mode 100644 index 863f55a..0000000 --- a/ovc-org-vet/index.md +++ /dev/null @@ -1,33 +0,0 @@ -## Org Vet Credentials - -### Purpose - -This credential asserts with an explicit level of assurance the existence and attributes of an organization. It is issued to a cryptographic identifier controlled by the org, allowing the org to authenticate itself on the basis of the credential. (The [LE vLEI](https://docs.origincloud.net/start/concepts/creds/vleis) is essentially an org vet credential at LoA 3, but its schema varies slightly to express some GLEIF governance requirements.) - -![suggested org vet visual](org-vet-256.png)
-Suggested visual: [svg](org-vet.svg) | [256 px](org-vet-256.png) | [128 px](org-vet-128.png) | [64 px](org-vet-64.png) | [32 px](org-vet-32.png) - -### Levels of assurance - -Levels of assurance (LoAs) are well known and often referenced for individual identity; they are less adopted in organizational identity. In the United States, the FBCA [defines](https://www.idmanagement.gov/docs/fbca-cp.pdf) *basic*, *medium*, and *high* assurance for certificates issued to federal agencies, but these LoAs are not typically referenced in other contexts. In the EU, eIDAS ([EU regulation 910/2014](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32014R0910), article 28) defines "nonqualified" and "qualified/QSeal" assurance for certificate issuance — but its rollout is young, and its application for non-certificate-based technologies is unclear. - -Org vet credentials convey a level of assurance with a positive number, where larger numbers map to higher levels of assurance (1 < 2 < 3). Normally, these numbers are expected to be integers, but nuances within a given integer can be modeled by using a floating point value instead (2.1 < 2.2). This allows verifiers to decide what level of assurance will satisfy them, and accept any credential having an LoA >= their threshhold. The meaning of the integer values are defined as follows: - -LoA | intended meaning | verification procedures | mappings ---- | --- | --- | --- -1 aka "bronze"| basic proof of control + authorization of requester; no claim about legalities, tools, governance, tools, or competence |
  1. Prove that a non-cryptographic identifier (e.g., an LEI) references an org that exists and is not defunct.
  2. Prove org owns domain.
  3. Prove requester is human and has email in domain.
  4. Prove requester has modified a DNS record for the domain to claim the issue's cryptographic identifier (AID).
| Similar to FBAC "basic" or eIDAS "nonqual". -2 aka "silver"| cryptographic proof of control + authz, legal accountability, tools; no claim about governance or competence |
  1. Satisfy requirements for LoA 1.
  2. Prove the legal identity of the requester via a digital credential having eIDAS *substantial* assurance, or use a physical credential that meets ISO/IEC 2915 LoA2 or NIST IAL2 requirements.
  3. Prove cryptographically (e.g., using a [GCD credential](../gcd/index.md) and/or a KERI delegated AID) that the requester was authorized by the org to request a credential for it.
  4. Use at least 1 witness for the org's AID.
| Similar to FBAC "medium", X509 extended verification, or eIDAS nonqual with deep vet. However, not a perfect analog; we are proving that the org has the tools to maintain their identity for a long time. -3 aka "gold" |
  1. Satisfy requirements for LoA 2.
  2. Prove that the requester has legal signing authority for the org.
    3. Prove that the org has a multisig signing committee to manage risk and human turnover.
  3. Issue the credential in a ceremony where it is proved that there is no MITM between any two members of the signing committee, and between each member of the signing committee and at least one external observer.
  4. Require that the AID of the org use enough witnesses to reliably detect and recover from duplicity.
| This approximates FBAC "high" and eIDAS "QSeal", but goes slightly beyond. It maps directly to the LE vLEI defined by GLEIF. -4 aka "platinum" | TBD, but could require use of hardware security and/or proof of specialized org attributes such as a security clearance. | none - - - - -### Schema - -See [org-vet.schema.json](org-vet.schema.json) and also [rules.json](rules.json). - -### Governance Framework - -These credentials are governed by rules to enhance assurance, discourage abuse, and keep use cases crisp. The current rules are stated in [rules.json](rules.json) and are identified by SAID `EFthNcTE20MLMaCOoXlSmNtdooGEbZF8uGmO5G85eMSF`. New governance frameworks can be written that supplement these rules; see the `gfw` field in the schema. It is also possible to modify or override these rules, by placing a different value in the `r` field. The act of issuing or receiving a GCD credential constitutes binding acceptance of the rules. - diff --git a/ovc-org-vet/org-vet-128.png b/ovc-org-vet/org-vet-128.png deleted file mode 100644 index 1032016..0000000 Binary files a/ovc-org-vet/org-vet-128.png and /dev/null differ diff --git a/ovc-org-vet/org-vet-256.png b/ovc-org-vet/org-vet-256.png deleted file mode 100644 index 9bf73ec..0000000 Binary files a/ovc-org-vet/org-vet-256.png and /dev/null differ diff --git a/ovc-org-vet/org-vet-32.png b/ovc-org-vet/org-vet-32.png deleted file mode 100644 index bc77d40..0000000 Binary files a/ovc-org-vet/org-vet-32.png and /dev/null differ diff --git a/ovc-org-vet/org-vet-64.png b/ovc-org-vet/org-vet-64.png deleted file mode 100644 index a253e9b..0000000 Binary files a/ovc-org-vet/org-vet-64.png and /dev/null differ diff --git a/ovc-org-vet/org-vet.svg b/ovc-org-vet/org-vet.svg deleted file mode 100644 index f801de9..0000000 --- a/ovc-org-vet/org-vet.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/ovc-org-vet/ovc-org-vet.schema.json b/ovc-org-vet/ovc-org-vet.schema.json deleted file mode 100644 index 06f0b3c..0000000 --- a/ovc-org-vet/ovc-org-vet.schema.json +++ /dev/null @@ -1,175 +0,0 @@ -{ - "$id": "EHFdm3U_4nML6lo-q_xDTO8183hC9HlWif2l4ycNo8TW", - "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "OVC Identity Credential", - "description": "Authenticate an org with an explicit level of assurance.", - "type": "object", - "credentialType": "orgVet", - "version": "1.0.0", - "required": [ - "v", - "d", - "i", - "ri", - "s", - "a", - "r" - ], - "properties": { - "v": { - "description": "Version string using ACDC conventions", - "type": "string" - }, - "d": { - "description": "SAID of the credential", - "type": "string" - }, - "i": { - "description": "Identifier of the issuer", - "type": "string" - }, - "ri": { - "description": "Issuer's ACDC status registry", - "type": "string" - }, - "s": { - "description": "SAID of this schema", - "type": "string" - }, - "a": { - "$id": "ELtdYgSHM9VElQtjd4P19IB24HH8PQZGbEctOjmP69QE", - "description": "Attributes block", - "type": "object", - "required": [ - "d", - "dt" - ], - "properties": { - "d": { - "description": "SAID of attributes block", - "type": "string" - }, - "dt": { - "description": "Issuance date (when the ACDC was signed).", - "format": "date-time", - "type": "string" - }, - "loa": { - "description": "Level of assurance.", - "type": "number" - }, - "lids": { - "description": "Array of linked identifiers (LIDs) that vetter claims were able to act as references for this legal entity when the org was vetted. At least one item in this list should be globally unambigious and portable across jurisdictions (e.g., an LEI). Others may come from national registries, OpenCorporates, EDGAR, Dun & Bradstreet, a stock exchange, a LinkedIn profile, a social media handle, a domain name, etc. The nature of individual item is detectable by regex match.", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "examples": [ - "5493001KJTIIGC8Y1R12", - "gb/01234567", - "CHE-123.456.789", - "12-345-6789", - "acmespacetravel.biz" - ], - "type": "string" - } - } - }, - "additionalProperties": true - }, - "r": { - "oneOf": [ - { - "description": "SAID of rules block", - "type": "string", - "const": "EM6kWxMNL9BFm0ReegqQfNJLw8OZAfn2ZxcjWs4Ceifh", - "format": "cesr" - }, - { - "$id": "EADZYJg0S3xZEKlhAChF8smXRFtVmer5ocBXQ3uuQt_h", - "description": "Rules detail", - "type": "object", - "required": [ - "d", - "onlyCommitToPoint", - "useViaEdges", - "undefinedVerification", - "undefinedRevocation" - ], - "properties": { - "d": { - "description": "SAID of rules block", - "type": "string" - }, - "onlyCommitToPoint": { - "description": "All parties agree that the citation, in and of itself, only commits the issuer to point at content in a way that makes the issuer and the target verifiable. Unless or until context, governance, or other actions prove intent, the citation does NOT imply that the issuer owns, endorses, or agrees with the content.", - "type": "string" - }, - "useViaEdges": { - "description": "All parties acknowledge that the citation is not intended to be used in isolation. Rather, the intended semantics for the citation should be communicated via a referencing ACDC that clarifies its issuer's intention.", - "type": "string" - }, - "undefinedVerification": { - "description": "All parties agree that procedures for evaluating the authenticity and/or veracity of the referenced content are beyond the scope of standard ACDC verification, and that the verifier is responsible for evaluating in whatever way satisfies their requirements.", - "type": "string" - }, - "undefinedRevocation": { - "description": "Unless or until governance specifies otherwise, all parties agree that there is no defined relationship between the revocation status of a citation and that of cited data. Cited data may be disavowed or revoked by its creator without a citation being revoked, and vice versa.", - "type": "string" - } - } - } - ] - }, - "e": { - "oneOf": [ - { - "description": "Edges block SAID", - "type": "string" - }, - { - "$id": "EKk5ejftEjNwjRhw2lYQAwKwvRWapqCNEOx3gUR7WW7n", - "description": "Edges detail", - "type": "object", - "required": [ - "d", - "issuer" - ], - "properties": { - "d": { - "description": "Edges block SAID", - "type": "string" - }, - "issuer": { - "description": "Edge credential that proves the identity of the issuer.", - "type": "object", - "properties": { - "n": { - "description": "SAID of a credential that proves the identity of the issuer", - "type": "string" - }, - "s": { - "description": "SAID of credential schema that proves the identity of the issuer", - "type": "string" - }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" - } - }, - "additionalProperties": false, - "required": [ - "n", - "s", - "o" - ] - } - }, - "additionalProperties": false - } - ] - } - }, - "additionalProperties": true -} \ No newline at end of file diff --git a/ovc-org-vet/rules.json b/ovc-org-vet/rules.json deleted file mode 100644 index 135f063..0000000 --- a/ovc-org-vet/rules.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "d": "EM6kWxMNL9BFm0ReegqQfNJLw8OZAfn2ZxcjWs4Ceifh", - "onlyCommitToPoint": "All parties agree that the citation, in and of itself, only commits the issuer to point at content in a way that makes the issuer and the target verifiable. Unless or until context, governance, or other actions prove intent, the citation does NOT imply that the issuer owns, endorses, or agrees with the content.", - "useViaEdges": "All parties acknowledge that the citation is not intended to be used in isolation. Rather, the intended semantics for the citation should be communicated via a referencing ACDC that clarifies its issuer's intention.", - "undefinedVerification": "All parties agree that procedures for evaluating the authenticity and/or veracity of the referenced content are beyond the scope of standard ACDC verification, and that the verifier is responsible for evaluating in whatever way satisfies their requirements.", - "undefinedRevocation": "Unless or until governance specifies otherwise, all parties agree that there is no defined relationship between the revocation status of a citation and that of cited data. Cited data may be disavowed or revoked by its creator without a citation being revoked, and vice versa." -} \ No newline at end of file diff --git a/registry.json b/registry.json index 14f952d..d9be46d 100644 --- a/registry.json +++ b/registry.json @@ -1,23 +1,21 @@ { - "EK3YbEFp3zUuHPsGrLRzwr6zWBXcOFJNTTBqezXd_2yf": "a2p-campaign/a2p-campaign.schema.json", + "ENjbevI70JxcQJaTrUQxMr4Ylcw0gbjfG2_skJyXy5XQ": "a2p-campaign/a2p-campaign.schema.json", "EKR1nFV0JvRhc4xkhzlZJfpN_taaspipcZWWSLj37Fdk": "aegis-std-vetting/aegis-std-vetting.schema.json", "EPhWFgeOy8g7yRy-Xtyvbdieqvl_3YVXNHMgTEZuJOWh": "ai-coder/ai-coder.schema.json", "EBCnd7qk82wLBOgFukdmsdkksAuPpmzt5-eg9YKWWP3j": "ai-user-coca/ai-user-coca.schema.json", "EJxFPpyDRV-W6O2Vtjdy2K90ltWmQK8l1jePw5YOo_Ft": "attestation/attestation.schema.json", "EBxJHMk6MOEUogB6A1rP5x9te7DscPfxFfUGJCkq1Lq5": "award/award.schema.json", "EFvHYHX0cUx9sdjxZOr9fpPcQKdzRNFH42D8R29p7lAH": "bindkey/bindkey.schema.json", - "EBpGNZSWwj-btOJMJSMLCVoXbtKdJTcggO-zMevr4vH_": "brand-owner/brand-owner.schema.json", + "EGNmJbfqUrgIi75YnTnyfZWJ15zRSvnStaxKZKH4_t4j": "brand-owner/brand-owner.schema.json", "EDH3Q0MW6oCcwyYw2MN39n1YfPs37o1QEv86kB-fBzmh": "citation/citation.schema.json", + "EHxI61CGs7FRuStz8P6QWJyMK4u2bGH1LQqIXsA4bT7q": "dossier-base/dossier-base.schema.json", "ELuPsd1mylvD9iY_gH5hEJzoUd8OZWtU6J2svJwIq-TJ": "faa/faa.schema.json", "EKrv2S0OVc8SeKCzIAOSE-y4j5ybLOOgB69y12Lzxh6Y": "face-to-face/face-to-face.schema.json", "EL7irIKYJL9Io0hhKSGWI4OznhwC7qgJG5Qf4aEs6j0o": "gcd/gcd.schema.json", - "EJvwY9n7EsJ4ZejUBHFrnrNammC8BkGI9YaW1Wnp5c22": "org-vet/org-vet.schema.json", - "EAoRVmgPyacjhUxaV0nPwiuUuHMjKDpNZrj7ClofZ-3Z": "ovc-brand-owner/ovc-brand-owner.schema.json", - "EHFdm3U_4nML6lo-q_xDTO8183hC9HlWif2l4ycNo8TW": "ovc-org-vet/ovc-org-vet.schema.json", + "EBCa5bot0IhTiuSD_jK4hjS4j9WsD2cocu8UXrG67Odi": "org-identity/org-identity.schema.json", "EG68irpfVX667KCLwG85Cn1Mp3sCe38ftARyQJrxP2kF": "proof-of-control/proof-of-control.schema.json", "EPy_7LE3tVdl8qEKN5i4L8eAgIM-1I51-DNiewmcq-fe": "tcr-vetting/tcr-vetting.schema.json", - "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ": "tn-alloc/tn-alloc.schema.json", - "EGEebb1pVRcZ6OXHlYitl5DNh-LDrMWPwRtstiKiDhRy": "tn/tn.schema.json", + "EMLnoJHFmFojtF1u-0hL4Eo8Ox2uTmxhrYEDOW_AhiID": "tn-alloc/tn-alloc.schema.json", "EH6ekLjSr8V32WyFbGe1zXjTzFs9PkTYmupJ9H65O14g": "vLEI/acdc/ecr-authorization-vlei-credential.json", "EEy9PkikFcANV1l7EHukCeXqrzT1hNZjGlUk7wuMO5jw": "vLEI/acdc/legal-entity-engagement-context-role-vLEI-credential.json", "EBNaNu-M9P5cgrnfl2Fvymy4E_jvxxyjb70PRtiANlJy": "vLEI/acdc/legal-entity-official-organizational-role-vLEI-credential.json", @@ -26,5 +24,5 @@ "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao": "vLEI/acdc/qualified-vLEI-issuer-vLEI-credential.json", "EMhvwOlyEJ9kN4PrwCpr9Jsv7TxPhiYveZ0oP3lJzdEi": "vLEI/acdc/verifiable-ixbrl-report-attestation.json", "ECYorXkheU7YsXZkYLGtvBOxEZ6alS5H5FJRn0tgDXV0": "vLEI/acdc/verifiable-ixbrl-report-d6-attestation.json", - "EH1jN4U4LMYHmPVI4FYdZ10bIPR7YWKp8TDdZ9Y9Al-P": "vvp-dossier/vvp-dossier.schema.json" + "EBiw7q5Q6WbFzGBbGfFXdn8_7zXTsvKOF8iEQV5C3dFn": "vvp-dossier/vvp-dossier.schema.json" } \ No newline at end of file diff --git a/tn-alloc/example-tn-alloc.json b/tn-alloc/example-tn-alloc.json index dbe32ea..024c2e7 100644 --- a/tn-alloc/example-tn-alloc.json +++ b/tn-alloc/example-tn-alloc.json @@ -1,32 +1,34 @@ { - "v": "ACDC10JSON0003cd_", - "d": "EEeg55Yr01gDyCScFUaE2QgzC7IOjQRpX2sTckFZp1RP", + "v": "ACDC10JSON00040b_", + "d": "EEPb0h9ClyxqrgiLt6hzhEmfEjv7FpVC4utFO09ZHsR9", "u": "0AC8kpfo-uHQvxkuGZdlSjGy", "i": "EANghOmfYKURt3rufd9JNzQDw_7sQFxnDlIew4C3YCnM", "ri": "EDoSO5PEPLsstDr_XXa8aHAf0YKfPlJQcxZvkpMSzQDB", - "s": "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ", + "s": "EJ9YoTJ81TcQ_pS9GmU2UbVURRm3ylnx_Wr1GbKjg0QP", "a": { - "d": "ECFFejktQA0ThTqLtAUTmW46unVGf28I_arbBFnIwnWB", - "u": "0ADSLntzn8x8eNU6PhUF26hk", - "i": "EERawEn-XgvmDR_-2ESVUVC6pW-rkqBkxMTsL36HosAz", - "dt": "2024-12-20T20:40:57.888000+00:00", - "numbers": { - "rangeStart": "+1801361002", - "rangeEnd": "+1801361009" - }, - "channel": "voice", - "doNotOriginate": false + "d": "EGSM6KZWVOXxmoNHlNNYBllu4DXs9Xx5-UhOnpTnDCO7", + "u": "0ADSLntzn8x8eNU6PhUF26hk", + "i": "EERawEn-XgvmDR_-2ESVUVC6pW-rkqBkxMTsL36HosAz", + "dt": "2024-12-20T20:40:57.888000+00:00", + "numbers": [ + "+1801361001-+1801361002", + "+1801361005" + ], + "channel": [ + "voice" + ] }, "e": { - "d": "EI9qlgiDbMeJ7JTZTJfVanUFAoa0TMz281loi63nCSAH", - "tnalloc": { - "n": "EG16t8CpJROovnGpgEW1_pLxH5nSBs1xQCbRexINYJgz", - "s": "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ", - "o": "I2I" - } + "d": "EHVafjATXqFvLkccHwmvjgNh-Yf-CoXoBCV35XVfa-EF", + "tnalloc": { + "n": "EG16t8CpJROovnGpgEW1_pLxH5nSBs1xQCbRexINYJgz", + "s": "EJ9YoTJ81TcQ_pS9GmU2UbVURRm3ylnx_Wr1GbKjg0QP", + "o": "I2I" + } }, "r": { - "d": "EJFhpp0uU7D7PKooYM5QIO1hhPKTjHE18sR4Dn0GFscR", - "perBrand": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." + "d": "EFC5aL2PUkGzu0BdKxWwL-jGkdqzKH8UQMrJg8T0HeYW", + "governance": "Issued under governance published at https://provenant.net/governance/tn-alloc/", + "noSharing": "Issuees agree not to share or lend the allocated telephone number(s) to other parties in a way that would make it difficult to consistently identify the originator of traffic." } } \ No newline at end of file diff --git a/tn-alloc/index.md b/tn-alloc/index.md index 7992f6c..ca5cfa0 100644 --- a/tn-alloc/index.md +++ b/tn-alloc/index.md @@ -1,5 +1,70 @@ -## Telephone Number (TN) Allocation Credentials +## Telephone Number Allocation Credential -#### Purpose +### Purpose -These credentials document the issuee's right to use a phone number to make phone calls. \ No newline at end of file +This credential proves that an enterprise or individual holds the **right to use (RTU)** one or more specific telephone numbers. The right-to-use may come directly from a telecommunications regulator or may be sub-allocated through a telephone number provider. The credential is channel-agnostic: the same number can carry voice calls, SMS messages, or both, and a single Telephone Number Allocation Credential covers the number regardless of channel. + +### Why this credential matters + +In telephony fraud and spam ecosystems, a caller or sender can trivially spoof any number they choose. Downstream recipients — call analytics platforms, carriers, campaign registries — have no way to distinguish a legitimate originator from a bad actor by looking at the calling number alone. The Telephone Number Allocation Credential establishes a cryptographic chain of custody from the regulator (who originally assigned the number block) to the enterprise that legitimately operates the number today. + +A verifier who holds this credential, together with the edges that chain back to the regulating authority, has a strong basis to assert that a call or message from the claimed number was originated by the holder of this credential — and only that holder. + +### Schema + +See [tn-alloc.schema.json](tn-alloc.schema.json). + +### Number expressions + +The `numbers` attribute is an array of **number expressions**. Each expression is either: + +- A **single E.164 number** — e.g., `+15551234567` +- An **inclusive range** — two E.164 numbers joined by a hyphen, e.g., `+15551230000-+15551239999` + +All numbers in a single credential must share the **same granting authority** — the issuer uses a single edge to point to the party that granted the right to use those numbers. If a holder has numbers from two different source authorities, they must hold two separate credentials. + +Verifiers evaluate each expression in the array. For a single number, it must match exactly. For a range, the number under test must be numerically between the start and end values, inclusive. + +### Multichannel readiness + +This schema supports both **voice** and **SMS** use cases without modification: + +- For **voice**, the holder uses the credential to assert origin identity when initiating a call. +- For **SMS / A2P campaigns**, the holder presents this credential to a campaign registry (e.g., The Campaign Registry) as proof of number ownership before campaign provisioning. The credential does not carry a campaign ID — campaign-level attributes belong in a separate campaign credential that references this one. + +The optional `channel` field can narrow the scope of the credential to a specific channel or set of channels. If omitted, no channel restriction is implied — the credential is valid for any use of the allocated numbers. If present, it is an array of one or both of `"sms"` and `"voice"`. + +| `channel` value | Meaning | +|---|---| +| `["voice"]` | Numbers are allocated for voice use only. | +| `["sms"]` | Numbers are allocated for SMS use only. | +| `["sms", "voice"]` | Numbers are allocated for both channels. | +| *(omitted)* | No channel restriction; allocation is channel-agnostic. | + +This design keeps number ownership and campaign intent cleanly separated, avoiding schema proliferation and making it easy to reuse the same number credential across multiple campaigns or channels over time. + +### Optional fields + +| Field | Type | Purpose | +|---|---|---| +| `channel` | array of `"sms"` / `"voice"` | Restricts the credential to specific channels. Omit for channel-agnostic allocation. | +| `startDate` | ISO-8601 datetime | Earliest date from which the allocation is valid. Useful for proving long-term continuous ownership. | +| `endDate` | ISO-8601 datetime | Expiry date of the allocation. If absent, the allocation is open-ended and governed solely by credential revocation. | + +### Edge structure + +The `e` (edges) block is optional to accommodate **regulators** who originate numbers directly and have no parent issuer. When present, the edges block may contain: + +| Edge | Required in block? | Purpose | +|---|---|---| +| `tnalloc` | No | Chain to a parent Telephone Number Allocation Credential, proving sub-allocation authority all the way back to the regulator. | +| `issuer` | No | Links to an identity credential (e.g., Org Identity, vLEI) that proves who the issuer is. Intentionally generic — does not constrain the schema of the identity credential. | + +### Rules and governance + +The `r` (rules) block must contain: + +- **`noSharing`** — The credential holder agrees not to share or lend the allocated numbers to other parties in a way that would obscure traffic origin. This rule exists because phone numbers are the accountability anchor for calls and messages: if a number is informally lent, regulators and recipients lose the ability to trace bad traffic back to a responsible party. +- **`governance`** — A statement identifying the governance framework under which this credential was issued. Issuers must populate this field with the URI of their applicable governance document. + +The act of issuing or accepting this credential constitutes binding acceptance of these rules. \ No newline at end of file diff --git a/tn-alloc/tn-alloc.schema.json b/tn-alloc/tn-alloc.schema.json index f540ea4..6d3ed08 100644 --- a/tn-alloc/tn-alloc.schema.json +++ b/tn-alloc/tn-alloc.schema.json @@ -1,15 +1,13 @@ { - "$id": "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "TN Allocation Credential", - "description": "TN Allocation credential proves an enterpise has the right to use(RTU) specific telephone numbers, either directly from a regulator or through a telephone number provider.", + "$id": "EMLnoJHFmFojtF1u-0hL4Eo8Ox2uTmxhrYEDOW_AhiID", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Telephone Number Allocation Credential", + "description": "Telephone Number Allocation credential proves an enterprise has the right to use (RTU) specific telephone numbers, either directly from a regulator or through a telephone number provider.", "type": "object", - "credentialType": "TNAllocationCredential", - "version": "1.0.0", + "version": "2.0.0", "required": [ "v", "d", - "u", "i", "ri", "s", @@ -18,28 +16,53 @@ ], "properties": { "v": { - "description": "Version", - "type": "string" + "description": "Version string using ACDC conventions, encoding protocol, serialization, and size.", + "type": "string", + "pattern": "^ACDC[0-9]{2}[A-Z]{4}[0-9a-f]{6}_$", + "examples": [ + "ACDC10JSON000345_" + ] }, "d": { - "description": "Credential SAID", - "type": "string" + "description": "SAID of the credential (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "u": { - "description": "A salty nonce", - "type": "string" + "description": "A salty nonce (high-entropy random value) used to prevent rainbow-table attacks on the credential SAID.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "Issuer AID", - "type": "string" + "description": "AID of the issuer (the party asserting the telephone number allocation right).", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EDC0Sj0CPYd70zUSY2ehvm7Z4kwZigugiA84wuS7lK2H", + "BCmx-dBiozRlK5MfRnznAHl9kmXjB3t-zxrE3hIIYkeS" + ] }, "ri": { - "description": "Credential status registry", - "type": "string" + "description": "SAID of the issuer's ACDC credential status registry.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EOkdwKgeEF-Ww2d61uhHjAo13rjJROdbdIaxORQJRV2G" + ] }, "s": { - "description": "Schema SAID", - "type": "string" + "description": "SAID of this schema (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EI8g4_JZ0zA50yihhsb-RXvOEcsI8TSN7PJrNgIbAUH1" + ] }, "a": { "oneOf": [ @@ -48,83 +71,124 @@ "type": "string" }, { - "$id": "EGgYbtyoE0qGfYfZWZ1lAd-UoWu_2OjqMcms_75s4atv", + "$id": "EBt9-R0JnIzJETIOsm9Lv2mbrGugADiSc9NF12mwyi44", "description": "Attributes block", "type": "object", "required": [ "d", - "u", "i", "dt", - "numbers", - "channel", - "doNotOriginate" + "numbers" ], "properties": { "d": { - "description": "Attributes block SAID", - "type": "string" + "description": "SAID of the attributes block (Blake3-256 digest in CESR compact encoding).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EGgYbtyoE0qGfYfZWZ1lAd-UoWu_2OjqMcms_75s4atv" + ] }, "u": { - "description": "A salty nonce", - "type": "string" + "description": "A salty nonce for the attributes block, enabling selective disclosure.", + "type": "string", + "pattern": "^0A[A-Za-z0-9_-]{22}$", + "examples": [ + "0AHcgNghkDaG7ts1Bv8wkv3b" + ] }, "i": { - "description": "Recipient Brand AID", - "type": "string" + "description": "AID of the credential recipient \u2014 the enterprise or individual that holds the right to use the allocated telephone numbers.", + "type": "string", + "pattern": "^[A-Za-z0-9_-]{44}$", + "examples": [ + "EAZz0-cvLBLfqw3TRo-J0kBzM1TEwQ6a_v_892uH3Yjz" + ] }, "dt": { - "description": "Issuance date time", + "description": "Issuance date-time (when the ACDC was signed), as an ISO-8601 datetime string with timezone.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2024-01-15T10:30:00.000000+00:00" + ] }, "numbers": { - "description": "Telephone Numbers allocated to enterpise either as a list of specific numbers or a range of numbers", - "type": "object", - "properties": { - "tn": { - "description": "Specific telephone numbers list", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "type": "string", - "description": "Telephone number in E164 format", - "pattern": "[+][0-9]{7,15}" - } - }, - "rangeStart": { - "description": "Range start number in E164 format, inclusive of this number. If provided, rangeEnd must also be provided", - "type": "string" - }, - "rangeEnd": { - "description": "Range end number in E164 format, inclusive of this number. If provided, rangeStart must also be provided", - "type": "string" - } + "description": "Array of number expressions representing telephone numbers allocated to the enterprise. Each expression is either a single E164 number (e.g., '+15551234567') or an inclusive range denoted by a hyphen between two E164 numbers (e.g., '+15551230000-+15551239999'). All numbers in a single credential must share the same granting authority.", + "type": "array", + "uniqueItems": true, + "minItems": 1, + "items": { + "type": "string", + "description": "A single E164 telephone number or an inclusive range. Single number: '+' followed by 7-15 digits. Range: two E164 numbers separated by a hyphen (e.g., '+15551230000-+15551239999').", + "pattern": "^\\+[1-9][0-9]{6,14}(-\\+[1-9][0-9]{6,14})?$" }, - "additionalProperties": false + "examples": [ + [ + "+15551234567" + ], + [ + "+15551230000-+15551239999" + ], + [ + "+15551234567", + "+442071234567" + ], + [ + "+15551230000-+15551239999", + "+15558880000-+15558889999" + ], + [ + "+15551234567", + "+15559876543", + "+442071234567", + "+81312345678" + ] + ] }, "channel": { - "description": "Communication channel for which number will be used (e.g., sms, voice, etc.)", - "type": "string", - "pattern": "sms|voice" - }, - "doNotOriginate": { - "description": "True or False based on condition if telephone number is a 'do not originate' number (inbound only)", - "type": "boolean" + "description": "Optional list of communication channels for which these numbers are allocated. If omitted, no channel restriction is implied. Use 'sms' for A2P/P2P messaging, 'voice' for voice calls, or both to indicate dual-channel use.", + "type": "array", + "uniqueItems": true, + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "sms", + "voice" + ] + }, + "examples": [ + [ + "voice" + ], + [ + "sms" + ], + [ + "sms", + "voice" + ] + ] }, "startDate": { - "description": "Start date", + "description": "Optional start date from which the telephone number allocation is valid (ISO-8601). Useful for proving long-term continuous ownership of a number.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2020-06-01T00:00:00.000000+00:00" + ] }, "endDate": { - "description": "Expiration date", + "description": "Optional expiration date of the telephone number allocation (ISO-8601). If omitted, the allocation is considered open-ended and subject only to credential revocation.", + "type": "string", "format": "date-time", - "type": "string" + "examples": [ + "2026-06-01T00:00:00.000000+00:00" + ] } }, - "additionalProperties": false + "additionalProperties": true } ] }, @@ -132,19 +196,24 @@ "oneOf": [ { "description": "Edges block SAID", - "type": "string" + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" }, { - "$id": "ED-ETRO9FOiEgvK8P66Rut-Cun-0aZ5FbgTlngPf9yVT", + "$id": "EO1vSj06OYTPF-qtTWEYFqgPPNhETasX3DQ0oEBc4uKM", "description": "Edges block", "type": "object", "properties": { "d": { - "description": "Edges block SAID", - "type": "string" + "description": "SAID of the edges block.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ED-ETRO9FOiEgvK8P66Rut-Cun-0aZ5FbgTlngPf9yVT" + ] }, "tnalloc": { - "description": "Chain to a TN allocation (RTU) credential that proves with a valid chain back to the regulator", + "description": "Chain to a telephone number allocation (RTU) credential that proves with a valid chain back to the regulator", "type": "object", "required": [ "n", @@ -153,15 +222,23 @@ ], "properties": { "n": { - "description": "SAID of TN allocation credential", - "type": "string" + "description": "SAID of a parent telephone number allocation credential that grants the issuer the right to sub-allocate.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EBwNam2e0mYdTx0i9xv78AIm16g1XCkQO8f8yJXaxmJC" + ] }, "s": { - "description": "SAID of TN allocation schema", - "type": "string" + "description": "SAID of the telephone number allocation schema that the chained credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EI8g4_JZ0zA50yihhsb-RXvOEcsI8TSN7PJrNgIbAUH1" + ] }, "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", + "description": "Issuer-To-Issuee, operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", "type": "string", "const": "I2I" } @@ -169,21 +246,35 @@ "additionalProperties": false }, "issuer": { - "description": "Edge credential that proves the identity of the issuer.", + "description": "Credential that proves the identity of the issuer.", "type": "object", "properties": { "n": { - "description": "SAID of a credential that proves the identity of the issuer", - "type": "string" + "description": "SAID of a credential that proves the identity of the issuer (e.g., an Org Identity or vLEI credential).", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "EG_rp79RWfT97mfVCiptp73PVKr26QHa-kAbMkTPqAno" + ] }, "s": { - "description": "SAID of credential schema that proves the identity of the issuer", - "type": "string" + "description": "SAID of the schema that the issuer identity credential must satisfy.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$", + "examples": [ + "ENPE4hUQ8Peu84tEcCni3koOQFOnBrDB0rg_at2NRhV9" + ] }, "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", "type": "string", - "const": "NI2I" + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ], + "default": "NI2I" } }, "additionalProperties": false, @@ -194,10 +285,9 @@ ] } }, - "additionalProperties": false, + "additionalProperties": true, "required": [ - "d", - "tnalloc" + "d" ] } ] @@ -205,29 +295,39 @@ "r": { "oneOf": [ { - "description": "Rules section SAID", - "type": "string" + "description": "SAID of rules block (Blake3-256 digest in CESR compact encoding)", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" }, { - "$id": "EHIN5MfIpe7_by-Rl7oVK6dDg1o096wds_gwtcsZInzj", + "$id": "EAmHGceHi6XHAXzbT1jwkgxd8_2k8QzlOE-VePPPFRal", "description": "Rules detail", "type": "object", "required": [ "d", - "perBrand" + "noSharing", + "governance" ], "properties": { "d": { - "description": "Rule section SAID", - "type": "string" + "description": "SAID of the rules block.", + "type": "string", + "pattern": "^E[A-Za-z0-9_-]{43}$" + }, + "governance": { + "description": "Statement identifying the governance framework under which this credential was issued.", + "type": "string", + "examples": [ + "Issued under governance published at https://provenant.net/governance/tn-alloc/" + ] }, - "perBrand": { - "description": "perBrand Disclaimer", + "noSharing": { + "description": "No Sharing Disclaimer", "oneOf": [ { "description": "simple compact rule form", "type": "string", - "const": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." + "default": "Issuees agree not to share or lend the allocated telephone number(s) to other parties in a way that would make it difficult to consistently identify the originator of traffic." }, { "description": "Rule detail", @@ -236,7 +336,7 @@ "l": { "description": "Associated legal language", "type": "string", - "const": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." + "default": "Issuees agree not to share or lend the allocated telephone number(s) to other parties in a way that would make it difficult to consistently identify the originator of traffic." } }, "required": [ @@ -247,7 +347,7 @@ ] } }, - "additionalProperties": false + "additionalProperties": true } ] } diff --git a/tn/example-tn.json b/tn/example-tn.json deleted file mode 100644 index 2ecbcfb..0000000 --- a/tn/example-tn.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "v": "ACDC10JSON00040c_", - "d": "EHhWLa-wy3agU2XrBQva9Aa_fn1quykH0g8VbEWLg4Oz", - "u": "0AD5Y0r_UJ3OaDC9ww7UcwMX", - "i": "EPf-n0htLTtNESESLTt4BuE-jadJtkomCNxlzos9pMOV", - "ri": "ENcuoFsOMgygryMcsWpMEoAwY9gzJGLmApjC6nVeFE9m", - "s": "EGEebb1pVRcZ6OXHlYitl5DNh-LDrMWPwRtstiKiDhRy", - "a": { - "d": "EPCnmKoZ8Sf_9QykiwXih2qjFveHcrhP0BVKSWd6ajpC", - "u": "0AB2S1oIA7MZcGgYMPnsQeCy", - "i": "EMqWlrNiLIyzsCebjb7mrGtn6RHNE359Y4iJSAmVMWdW", - "dt": "2024-12-17T11:22:07.958000+00:00", - "numbers": { - "rangeStart": "+1801361002", - "rangeEnd": "+1801361009" - }, - "channel": "voice", - "doNotOriginate": false, - "startDate": "2024-12-25T20:20:39+00:00", - "endDate": "2024-11-29T20:20:39+00:00" - }, - "e": { - "d": "ELgUHQasEuGtntBtXLE7zlxFYTR5vRi8M3GMgqHxWVYN", - "le": { - "n": "EJDQgxYJJR_4AZwcjrdwQASgVwdYb0VfQskrFkGnVbUw", - "s": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" - } - }, - "r": { - "d": "EJFhpp0uU7D7PKooYM5QIO1hhPKTjHE18sR4Dn0GFscR", - "perBrand": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." - } -} \ No newline at end of file diff --git a/tn/index.md b/tn/index.md deleted file mode 100644 index 1719bc6..0000000 --- a/tn/index.md +++ /dev/null @@ -1,5 +0,0 @@ -## Telephone Number (TN) Credentials - -#### Purpose - -These credentials document the issuee's right to use a phone number to send A2P messages. \ No newline at end of file diff --git a/tn/tn.schema.json b/tn/tn.schema.json deleted file mode 100644 index ec02bb5..0000000 --- a/tn/tn.schema.json +++ /dev/null @@ -1,229 +0,0 @@ -{ - "$id": "EGEebb1pVRcZ6OXHlYitl5DNh-LDrMWPwRtstiKiDhRy", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Telephone Number Credential", - "description": "Telephone Number Credential issued to a Brand for A2P 10DLC messaging campaigns", - "type": "object", - "credentialType": "TelephoneNumberCredential", - "version": "1.0.0", - "required": [ - "v", - "d", - "u", - "i", - "ri", - "s", - "a", - "e", - "r" - ], - "properties": { - "v": { - "description": "Version", - "type": "string" - }, - "d": { - "description": "Credential SAID", - "type": "string" - }, - "u": { - "description": "A salty nonce", - "type": "string" - }, - "i": { - "description": "Issuer AID", - "type": "string" - }, - "ri": { - "description": "Credential status registry", - "type": "string" - }, - "s": { - "description": "Schema SAID", - "type": "string" - }, - "a": { - "oneOf": [ - { - "description": "Attributes block SAID", - "type": "string" - }, - { - "$id": "EPBlIaGwdiP_PaMZHbIOUPtJ20qX4LaHbIzDZT4KAWtt", - "description": "Attributes block", - "type": "object", - "required": [ - "d", - "u", - "i", - "dt", - "numbers", - "channel", - "doNotOriginate", - "startDate", - "endDate" - ], - "properties": { - "d": { - "description": "Attributes block SAID", - "type": "string" - }, - "u": { - "description": "A salty nonce", - "type": "string" - }, - "i": { - "description": "Recipient Brand AID", - "type": "string" - }, - "dt": { - "description": "Issuance date time", - "format": "date-time", - "type": "string" - }, - "numbers": { - "description": "Telephone Numbers allocated to brand either as a list of specific numbers or a range of numbers", - "type": "object", - "properties": { - "tn": { - "description": "Specific telephone numbers list", - "type": "array", - "uniqueItems": true, - "minItems": 1, - "items": { - "type": "string", - "description": "Telephone number in E164 format", - "pattern": "[+][0-9]{7,15}" - } - }, - "rangeStart": { - "description": "Range start number in E164 format, inclusive of this number. If provided, rangeEnd must also be provided", - "type": "string" - }, - "rangeEnd": { - "description": "Range end number in E164 format, inclusive of this number. If provided, rangeStart must also be provided", - "type": "string" - } - }, - "additionalProperties": false - }, - "channel": { - "description": "Communication channel for which number will be used (e.g., sms, voice, etc.)", - "type": "string", - "pattern": "sms|voice" - }, - "doNotOriginate": { - "description": "True or False based on condition if telephone number is a 'do not originate' number (inbound only)", - "type": "boolean" - }, - "startDate": { - "description": "Start date", - "format": "date-time", - "type": "string" - }, - "endDate": { - "description": "Expiration date", - "format": "date-time", - "type": "string" - } - }, - "additionalProperties": false - } - ] - }, - "e": { - "oneOf": [ - { - "description": "Edges block SAID", - "type": "string" - }, - { - "$id": "EJrEovSBvm4odgfVI9zldtlju8_lD2m1gDiryDqvB8Lt", - "description": "Edges block", - "type": "object", - "properties": { - "d": { - "description": "Edges block SAID", - "type": "string" - }, - "le": { - "description": "Chain to legal entity vLEI credential", - "type": "object", - "properties": { - "n": { - "description": "SAID of Legal Entity vLEI Credential issued by a Qualified vLEI issuer to a Legal Entity", - "type": "string" - }, - "s": { - "description": "SAID of Legal Entity vLEI Credential schema", - "type": "string", - "const": "ENPXp1vQzRF6JwIuS-mp2U8Uf1MoADoP_GqQ62VsDZWY" - } - }, - "additionalProperties": false, - "required": [ - "n", - "s" - ] - } - }, - "additionalProperties": false, - "required": [ - "d", - "le" - ] - } - ] - }, - "r": { - "oneOf": [ - { - "description": "Rules section SAID", - "type": "string" - }, - { - "$id": "EHIN5MfIpe7_by-Rl7oVK6dDg1o096wds_gwtcsZInzj", - "description": "Rules detail", - "type": "object", - "required": [ - "d", - "perBrand" - ], - "properties": { - "d": { - "description": "Rule section SAID", - "type": "string" - }, - "perBrand": { - "description": "perBrand Disclaimer", - "oneOf": [ - { - "description": "simple compact rule form", - "type": "string", - "const": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." - }, - { - "description": "Rule detail", - "type": "object", - "properties": { - "l": { - "description": "Associated legal language", - "type": "string", - "const": "Issuees agree not to share the phone number with other brands which may have a common owner but which will make it difficult to consistently identify the originator of traffic." - } - }, - "required": [ - "l" - ], - "additionalProperties": false - } - ] - } - }, - "additionalProperties": false - } - ] - } - }, - "additionalProperties": false -} \ No newline at end of file diff --git a/vvp-dossier/index.md b/vvp-dossier/index.md new file mode 100644 index 0000000..8e760ec --- /dev/null +++ b/vvp-dossier/index.md @@ -0,0 +1,52 @@ +## Verifiable Voice Dossier + +### Purpose + +This dossier packages the evidence needed to support a Verifiable Voice Protocol workflow. It is the container that ties together the accountable party, the telephone number allocation, delegated signing authority, and any brand or campaign evidence needed to justify the voice/messaging activity. + +The schema is structured so that the dossier itself stays lightweight while the actual proof material lives in the edge block. + +### Schema + +See [vvp-dossier.schema.json](vvp-dossier.schema.json). + +### Basic structure + +The dossier has two main parts: + +- `a` holds proximate metadata about the dossier itself, including its name, issuance time, assembly time, and purpose. +- `e` holds the evidence graph that links the dossier to the credentials the verifier needs to inspect. + +### Required evidence + +The current schema requires these edge references: + +- `vetting` - proves the identity of the accountable party. +- `tnalloc` - proves right to use the telephone numbers involved. +- `delsig` - proves the signer is authorized to sign on behalf of the legal entity. + +### Optional evidence + +The schema also supports additional links when the use case needs them: + +- `alloc` - accountable party tn managers +- `bownr` - brand ownership evidence. +- `bproxy` - brand proxy evidence for call-center representation. +- `a2pcamp` - A2P campaign evidence tied to the dossier. + +### Multichannel readiness + +Although the dossier is centered on voice workflows, it already anticipates related messaging evidence. The presence of `tnalloc` and `a2pcamp` lets the same dossier model support cases where a number, a delegated signer, and an approved campaign all need to be shown together. + +This is useful when the same accountable party is operating across voice and SMS, because the dossier can carry the shared identity and number evidence once and then reference the channel-specific campaign or authorization material as needed. + +### Dossier metadata + +The `a` block is where the dossier is identified and described. The schema currently requires: + +- `d` - SAID of the attributes block. +- `dt` - issuance datetime. +- `assembly_dt` - the time the dossier was assembled. +- `purpose` - a short statement describing why the dossier exists. + +The optional `name` field can be used as a human-readable label. diff --git a/vvp-dossier/vvp-dossier.schema.json b/vvp-dossier/vvp-dossier.schema.json index 8be7615..f98ec4e 100644 --- a/vvp-dossier/vvp-dossier.schema.json +++ b/vvp-dossier/vvp-dossier.schema.json @@ -1,240 +1,330 @@ { - "$id": "EH1jN4U4LMYHmPVI4FYdZ10bIPR7YWKp8TDdZ9Y9Al-P", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Verifiable Voice Dossier Credential", - "description": "Attestation credential, issued by the accountable party, that assembles all of the evidence required as per the Verifiable Voice Protocol", - "type": "object", - "credentialType": "VvpDossierCredential", - "version": "1.0.0", - "required": [ - "v", - "d", - "i", - "ri", - "s", - "a", - "e" - ], - "properties": { - "v": { - "description": "Version", - "type": "string" + "$id": "EBiw7q5Q6WbFzGBbGfFXdn8_7zXTsvKOF8iEQV5C3dFn", + "title": "Verifiable Voice Dossier", + "description": "Dossier issued by the accountable party that assembles all evidence required as per the Verifiable Voice Protocol.", + "version": "2.0.0", + "allOf": [ + { + "description": "Reference to dossier base schema.", + "$ref": "EHxI61CGs7FRuStz8P6QWJyMK4u2bGH1LQqIXsA4bT7q" }, - "d": { - "description": "Credential SAID", - "type": "string" - }, - "i": { - "description": "Issuer AID", - "type": "string" - }, - "ri": { - "description": "Credential status registry", - "type": "string" - }, - "s": { - "description": "Schema SAID", - "type": "string" - }, - "a": { - "$id": "EAwY8VfT_6wtHBzpHhK01cbFSJLLd3wLUZwP8wcfHR7M", - "description": "Attributes block", + { "type": "object", + "additionalProperties": true, + "required": [ + "v", + "d", + "i", + "ri", + "s", + "a", + "e" + ], "properties": { + "v": { + "description": "Version", + "type": "string" + }, "d": { - "description": "Attributes block SAID", + "description": "Credential SAID", "type": "string" }, - "dt": { - "description": "Issuance datetime, ISO-8601 datetime string", - "format": "date-time", + "i": { + "description": "Issuer AID", "type": "string" }, - "name": { - "description": "A human-readable name for the dossier credential, useful for identification or labeling. This field is optional", + "ri": { + "description": "Credential status registry", "type": "string" - } - }, - "additionalProperties": false, - "required": [ - "d", - "dt" - ] - }, - "e": { - "oneOf": [ - { - "description": "Edges section SAID", + }, + "s": { + "description": "Schema SAID", "type": "string" }, - { - "$id": "EH8ahNIz4OhynHwrs0L4eUX3ZSeWADEoJS7d_D6hUHQq", - "description": "Edges detail", - "type": "object", - "required": [ - "d", - "vetting", - "alloc", - "tnalloc", - "delsig" - ], - "properties": { - "d": { - "description": "Edges section SAID", - "type": "string" + "a": { + "description": "Proximate metadata about the dossier itself.", + "oneOf": [ + { + "type": "string", + "description": "Compact form: SAID of the attributes block." }, - "vetting": { - "description": "Chain to a credential proves the identity of the accountable party", + { + "$id": "EAwY8VfT_6wtHBzpHhK01cbFSJLLd3wLUZwP8wcfHR7M", + "description": "Attributes block", "type": "object", + "additionalProperties": true, "required": [ - "n", - "s", - "o" + "d", + "dt", + "assembly_dt", + "purpose" ], "properties": { - "n": { - "description": "SAID of credential that proves the identity of the issuer", + "d": { + "description": "Attributes block SAID", "type": "string" }, - "s": { - "description": "SAID of the vetting schema", + "dt": { + "description": "Issuance datetime, ISO-8601 datetime string", + "format": "date-time", "type": "string" }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MAY or MAY not be the Issuee AID of this node.", - "type": "string", - "const": "NI2I" - } - }, - "additionalProperties": false - }, - "alloc": { - "description": "Chain to allocator credential for the committee that manages TN allocations at the accountable party legal entity", - "type": "object", - "required": [ - "n", - "s", - "o" - ], - "properties": { - "n": { - "description": "SAID of allocator auth credential", + "name": { + "description": "A human-readable name for the dossier, useful for identification or labeling.", "type": "string" - }, - "s": { - "description": "SAID of allocator auth schema", - "type": "string", - "const": "EL7irIKYJL9Io0hhKSGWI4OznhwC7qgJG5Qf4aEs6j0o" - }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" } - }, - "additionalProperties": false + } + } + ] + }, + "e": { + "description": "Edges \u2014 references to the VVP evidence credentials. Primary evidence MUST enter the dossier through this section.", + "oneOf": [ + { + "type": "string", + "description": "Compact form: SAID of the edges block." }, - "tnalloc": { - "description": "Chain to a TN allocation (RTU) credential that proves with a valid chain back to the regulator", + { + "$id": "EH8ahNIz4OhynHwrs0L4eUX3ZSeWADEoJS7d_D6hUHQq", + "description": "Edges block", "type": "object", + "additionalProperties": true, "required": [ - "n", - "s", - "o" + "d", + "vetting", + "tnalloc", + "delsig" ], "properties": { - "n": { - "description": "SAID of TN allocation credential", + "d": { + "description": "Edges block SAID", "type": "string" }, - "s": { - "description": "SAID of TN allocation schema", - "type": "string", - "const": "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ" + "vetting": { + "description": "Chain to a credential that proves the identity of the accountable party.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of credential that proves the identity of the issuer", + "type": "string" + }, + "s": { + "description": "SAID of the vetting schema", + "type": "string" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "I2I" - } - }, - "additionalProperties": false - }, - "delsig": { - "description": "Chain to a delegated signer credential proving that the party that signed is authorized to sign on behalf of the legal entity ", - "type": "object", - "required": [ - "n", - "s", - "o" - ], - "properties": { - "n": { - "description": "SAID of delegated signer credential", - "type": "string" + "alloc": { + "description": "Chain to allocator credential for the committee that manages TN allocations at the accountable party legal entity.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of allocator auth credential", + "type": "string" + }, + "s": { + "description": "SAID of allocator auth schema", + "type": "string", + "const": "EL7irIKYJL9Io0hhKSGWI4OznhwC7qgJG5Qf4aEs6j0o" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "s": { - "description": "SAID of delegated signer schema", - "type": "string", - "const": "EL7irIKYJL9Io0hhKSGWI4OznhwC7qgJG5Qf4aEs6j0o" + "tnalloc": { + "description": "Chain to a TN allocation (RTU) credential that proves with a valid chain back to the regulator.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of TN allocation credential", + "type": "string" + }, + "s": { + "description": "SAID of TN allocation schema", + "type": "string", + "const": "EFvnoHDY7I-kaBBeKlbDbkjG4BaI0nKLGadxBdjMGgSQ" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "I2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MAY or MAY not be the Issuee AID of this node.", - "type": "string", - "const": "NI2I" - } - }, - "additionalProperties": false - }, - "bownr": { - "description": "Chain to a brand ownership credential that proves a company has the legal right to use specific brand names, logos, and related brand assets.", - "type": "object", - "required": [ - "n", - "s", - "o" - ], - "properties": { - "n": { - "description": "SAID of brand ownership credential", - "type": "string" + "delsig": { + "description": "Chain to a delegated signer credential proving that the party that signed is authorized to sign on behalf of the legal entity.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of delegated signer credential", + "type": "string" + }, + "s": { + "description": "SAID of delegated signer schema", + "type": "string", + "const": "EL7irIKYJL9Io0hhKSGWI4OznhwC7qgJG5Qf4aEs6j0o" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "s": { - "description": "SAID of brand ownership schema", - "type": "string" + "bownr": { + "description": "Chain to a brand ownership credential that proves a company has the legal right to use specific brand names, logos, and related brand assets.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of brand ownership credential", + "type": "string" + }, + "s": { + "description": "SAID of brand ownership schema", + "type": "string" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "o": { - "description": "Operator indicating issuer AID of this ACDC MUST be the Issuee AID of the node this Edge points to.", - "type": "string", - "const": "NI2I" - } - }, - "additionalProperties": false - }, - "bproxy": { - "description": "Chain to a brand proxy credential that authorizes a call center to represent another company's brand when making calls on their behalf.", - "type": "object", - "required": [ - "n", - "s" - ], - "properties": { - "n": { - "description": "SAID of brand proxy credential", - "type": "string" + "bproxy": { + "description": "Chain to a brand proxy credential that authorizes a call center to represent another company's brand when making calls on their behalf.", + "type": "object", + "required": [ + "n", + "s" + ], + "properties": { + "n": { + "description": "SAID of brand proxy credential", + "type": "string" + }, + "s": { + "description": "SAID of brand proxy schema", + "type": "string" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false }, - "s": { - "description": "SAID of brand proxy schema", - "type": "string" + "a2pcamp": { + "description": "Chain to an A2P campaign credential associated with this messaging activity.", + "type": "object", + "required": [ + "n", + "s", + "o" + ], + "properties": { + "n": { + "description": "SAID of A2P campaign credential", + "type": "string" + }, + "s": { + "description": "SAID of A2P campaign credential schema", + "type": "string" + }, + "o": { + "description": "Edge operator. I2I (default): issuer AID MUST be the issuee AID of the node this edge points to. NI2I: issuer AID MAY or MAY NOT be the issuee AID of that node. DI2I: issuer AID MUST be the issuee AID or a delegated AID of the issuee AID of that node. NOT: inverts the validity of the node this edge points to.", + "type": "string", + "default": "NI2I", + "enum": [ + "I2I", + "NI2I", + "DI2I", + "NOT" + ] + } + }, + "additionalProperties": false } - }, - "additionalProperties": true + } } - }, - "additionalProperties": false + ] } - ] + } } - }, - "additionalProperties": false + ] } \ No newline at end of file