@trustlayer-foundation/aria-sdk 0.0.0-stage → 1.0.1

package/schemas/aid-1.0.json

@@ -0,0 +1,394 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aria.bar/schema/aid-1.0.json",
+  "title": "ARIA Identity Document (AID) 1.0 (draft until the issuance cutover)",
+  "description": "JSON Schema for the ARIA Identity Document (AID) \u2014 a W3C Verifiable Credential (VC Data Model 2.0) that serves as the cryptographically signed identity document of an AI agent, anchored to DNS from L1. ARIA 1.0. The credential carries the agent's holder key (Ed25519, generated by the controller; the registry never holds the private half), a principal reference, the derived trust level and the scopes, and is secured by the composite mldsa65-ed25519-2026 proof. The schema is the authority: where prose and schema disagree, the schema wins.",
+  "type": "object",
+  "required": [
+    "@context",
+    "type",
+    "id",
+    "issuer",
+    "validFrom",
+    "validUntil",
+    "credentialSubject",
+    "credentialStatus",
+    "proof"
+  ],
+  "properties": {
+    "@context": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "format": "uri"
+      },
+      "minItems": 2,
+      "prefixItems": [
+        {
+          "const": "https://www.w3.org/ns/credentials/v2"
+        },
+        {
+          "const": "https://aria.bar/ns/v1"
+        }
+      ],
+      "description": "JSON-LD context. Must include the W3C VC v2 context and the ARIA v1 context."
+    },
+    "type": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 2,
+      "contains": {
+        "const": "VerifiableCredential"
+      },
+      "prefixItems": [
+        {
+          "const": "VerifiableCredential"
+        },
+        {
+          "const": "ARIAIdentityDocument"
+        }
+      ],
+      "description": "Credential type. Must include VerifiableCredential and ARIAIdentityDocument."
+    },
+    "id": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://api\\.aria\\.bar/v1/credentials/[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+      "description": "Unique credential-instance identifier per W3C VC 2.0 \u00a74.4 \u2014 a dereferenceable URL containing a UUIDv7 (RFC 9562). NOT the agent DID (the DID lives in credentialSubject.id). Each issuance produces a new id; the URL resolves to that specific signed instance, active or revoked. Equivalent to a TLS certificate serial number."
+    },
+    "issuer": {
+      "type": "string",
+      "pattern": "^did:aria:.+$",
+      "description": "The DID of the issuing registry. Typically did:aria:registry.aria.bar."
+    },
+    "validFrom": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime when the credential becomes valid."
+    },
+    "validUntil": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime when the credential expires. Maximum 1-year validity from issuance."
+    },
+    "credentialStatus": {
+      "type": "object",
+      "required": [
+        "id",
+        "type",
+        "statusPurpose",
+        "statusListIndex",
+        "statusListCredential"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri",
+          "description": "URI identifying the status entry. Format: <statusListCredential>#<index>."
+        },
+        "type": {
+          "type": "string",
+          "const": "BitstringStatusListEntry",
+          "description": "W3C Bitstring Status List v1.0 entry type."
+        },
+        "statusPurpose": {
+          "type": "string",
+          "const": "revocation",
+          "description": "Purpose of the status check. Always 'revocation' for AID documents."
+        },
+        "statusListIndex": {
+          "type": "string",
+          "pattern": "^[0-9]+$",
+          "description": "Index position in the status list bitstring."
+        },
+        "statusListCredential": {
+          "type": "string",
+          "format": "uri",
+          "description": "URI of the StatusList credential containing the bitstring."
+        }
+      },
+      "additionalProperties": false,
+      "description": "W3C Bitstring Status List v1.0 revocation entry."
+    },
+    "credentialSubject": {
+      "type": "object",
+      "required": [
+        "id",
+        "agentName",
+        "version",
+        "trustLevel",
+        "scope",
+        "delegationDepth",
+        "maxDelegationDepth",
+        "spec_version",
+        "principal",
+        "holderKey",
+        "enrollmentAttestation"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^did:aria:[a-zA-Z0-9.-]+:[a-zA-Z0-9-]+(:[a-zA-Z0-9-]+)?$",
+          "description": "The DID of the agent. Stable across reissuances. Two acceptable formats: did:aria:{verified-domain}:{agent-name} when the principal organization has DNS-verified its own domain, OR did:aria:{registry-host}:{principal-short-id}:{agent-name} when the agent lives under the registry-namespaced fallback (e.g. did:aria:aria.bar:u-abc12345:ordering-agent). The unique per-issuance identifier lives at the top-level 'id' field per W3C VC 2.0."
+        },
+        "previousCredentialId": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://api\\.aria\\.bar/v1/credentials/[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+          "description": "Optional. URL of the previous credential instance for this DID \u2014 set when this AID supersedes an earlier one. Enables chain-of-issuance traceability. Omitted on first issuance. The URL resolves to the predecessor's signed AID document (which by then is revoked in the StatusList)."
+        },
+        "holderKey": {
+          "type": "object",
+          "required": [
+            "id",
+            "type",
+            "publicKeyMultibase"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^did:aria:[a-zA-Z0-9.-]+:[a-zA-Z0-9-]+(:[a-zA-Z0-9-]+)?#holder-key-[0-9]+$",
+              "description": "DID URL identifying this holder key. Format: <agentDID>#holder-key-<n> where n is monotonically increasing per re-issuance."
+            },
+            "type": {
+              "type": "string",
+              "const": "Ed25519VerificationKey2020",
+              "description": "W3C verification method type. Always Ed25519VerificationKey2020 for ARIA 1.0."
+            },
+            "publicKeyMultibase": {
+              "type": "string",
+              "pattern": "^z[1-9A-HJ-NP-Za-km-z]+$",
+              "description": "'z' + base58btc of the raw 32-byte Ed25519 public key. This is ARIA's own encoding, not Multikey (whose form of the same key adds the 0xed01 prefix). The agent generates the key pair and submits only the public key; no registry or authority ever holds the private key."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Holder verification key (Ed25519) bound to this AID. Possession is proved by signing with the corresponding private key: under ARIA AP, every request is signed with it. Verifiers MUST extract this key from the SIGNED credentialSubject \u2014 never from external sources such as the registry database \u2014 to preserve the PQC integrity guarantee. Re-issuance uses the key pair the agent submits for it; old holder proofs remain verifiable against superseded AIDs but not against the current one."
+        },
+        "agentName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$",
+          "description": "Human-readable agent name. 1-64 characters, alphanumeric and hyphens only. Must start and end with an alphanumeric character."
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+          "description": "Semantic version of the agent software."
+        },
+        "trustLevel": {
+          "type": "string",
+          "enum": [
+            "L0",
+            "L1",
+            "L2",
+            "L3"
+          ],
+          "description": "Trust level assigned to the agent. L0=Anchored, L1=Identified, L2=Certified, L3=Sovereign."
+        },
+        "scope": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*(:[a-z][a-z0-9_]*)*$",
+            "description": "Scope in ARIA namespace format: namespace:resource:action."
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "The scopes the agent declared at enrollment: what it intends to do. Each receiver decides whether to admit them; a scope here grants nothing by itself."
+        },
+        "hitlRequired": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "description": "Scopes, among those declared, whose operations need a person's approval. Under ARIA AP a receiver refuses such an operation when no valid approval accompanies it; it does not hold the operation waiting."
+        },
+        "delegationDepth": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4,
+          "description": "Current delegation depth. 0 means directly issued by the principal."
+        },
+        "maxDelegationDepth": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4,
+          "description": "Maximum allowed delegation depth for further sub-delegations."
+        },
+        "spec_version": {
+          "type": "string",
+          "const": "1.0",
+          "description": "ARIA specification version. Must be '1.0' for credentials issued under ARIA 1.0. The issuance regime is distinguished by the issuer DID, not by this value."
+        },
+        "principal": {
+          "type": "object",
+          "required": [
+            "did",
+            "jurisdiction",
+            "verificationStatus"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "Person",
+                "Organization"
+              ],
+              "description": "Kind of principal, as a schema.org type: Person for a natural person, Organization for any legal entity. A Person principal carries no legalName, because the public AID never carries a natural person's name (COM-09). When absent \u2014 credentials issued before this field existed \u2014 legalName is required, as it always was."
+            },
+            "did": {
+              "type": "string",
+              "description": "DID of the principal (legal entity or person) on whose behalf the agent operates."
+            },
+            "legalName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256,
+              "description": "Legal name of the principal ORGANIZATION. Required when type is Organization or absent; MUST be absent when type is Person, because the public AID never carries a natural person's name (COM-09, L0-03). At L0 the name is registrant-asserted and verificationStatus says so. A natural-person principal whose document carries its name here is non-conformant, and a validator now rejects it once type is set."
+            },
+            "jurisdiction": {
+              "type": "string",
+              "pattern": "^[A-Z]{2}$",
+              "description": "ISO 3166-1 alpha-2 country code of the principal's legal jurisdiction."
+            },
+            "verificationStatus": {
+              "type": "string",
+              "enum": [
+                "self-declared",
+                "registry-confirmed",
+                "legal-verified"
+              ],
+              "description": "Machine-readable provenance of the principal's declared identity \u2014 of legalName, for an Organization. self-declared: registrant-asserted, no external check (L0, L1). registry-confirmed: confirmed against the Authoritative Source of the jurisdiction of incorporation (L2). legal-verified: backed by government-issued legal documents and admin review (L3). Verifiers MUST consult this field before treating legalName as authoritative."
+            }
+          },
+          "if": {
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "const": "Person"
+              }
+            }
+          },
+          "then": {
+            "not": {
+              "required": [
+                "legalName"
+              ]
+            }
+          },
+          "else": {
+            "required": [
+              "legalName"
+            ]
+          },
+          "additionalProperties": false,
+          "description": "The legal principal (organization or person) responsible for the agent."
+        },
+        "dnsAnchor": {
+          "type": "string",
+          "description": "DNS TXT record content anchoring this AID to the principal's domain. Format: v=ARIA1;id=<did>;h=sha256:<hash>;r=<resolution-url>."
+        },
+        "alsoKnownAs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri",
+            "pattern": "^did:[a-z0-9]+:.+$"
+          },
+          "uniqueItems": true,
+          "maxItems": 5,
+          "description": "Optional. External DIDs the agent declared at enrollment as alternative identifiers, per W3C DID Core \u00a75.1.2. In ARIA 1.0 each entry was syntactically validated AND verified for proof-of-control at enrollment time (the principal signed a session-bound challenge from the external DID's key). However, this field is DORMANT for trust decisions in ARIA 1.0: verifiers MUST NOT treat alsoKnownAs entries as authoritative when evaluating trust level, scope authority, or principal identity. The field is preserved in the AID for forward compatibility \u2014 activation of cross-method interop and the DID-method allow-list is on the roadmap of a later revision."
+        },
+        "enrollmentAttestation": {
+          "type": "object",
+          "required": [
+            "userAgentAgreement",
+            "attestedAt",
+            "termsVersion",
+            "privacyVersion"
+          ],
+          "properties": {
+            "userAgentAgreement": {
+              "type": "boolean",
+              "const": true,
+              "description": "Always true in a valid AID. Confirms that issuance occurred through the authenticated enrollment flow defined in ARIA Spec ARIA 1.0 \u00a7Enrollment: (a) the principal initiated the enrollment from an authenticated registry session, (b) an SDK on the agent's infrastructure generated a composite keypair locally and self-signed an enrollment manifest, (c) DNS proof-of-control was verified for trust levels L1+, (d) the principal confirmed the manifest contents and authorized issuance with a fresh second factor. Implicit acceptance of the Terms of Service and Privacy Policy versions referenced below."
+            },
+            "attestedAt": {
+              "type": "string",
+              "format": "date-time",
+              "description": "ISO 8601 timestamp of the admin's second-factor confirmation that authorized signing this AID. Anchors the contractual moment of issuance. Must equal or precede the top-level validFrom timestamp; registry rejects on inversion."
+            },
+            "termsVersion": {
+              "type": "string",
+              "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+              "description": "Semantic version of the Terms of Service the principal accepted at enrollment. Resolves to the immutable document at https://aria.bar/terms/{termsVersion}. CRITICAL: this is the version the principal LAST ACCEPTED, NOT the registry's current version at issuance time. Preserves legal traceability across non-breaking ToS updates: if the registry advances to a newer minor/patch version without forcing re-acceptance, AIDs continue to embed the version the principal actually saw and accepted."
+            },
+            "privacyVersion": {
+              "type": "string",
+              "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+              "description": "Semantic version of the Privacy Policy the principal accepted at enrollment. Same last-accepted semantics as termsVersion. Resolves to https://aria.bar/privacy/{privacyVersion}."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Declarative attestation embedded in the AID confirming that issuance occurred through the authenticated enrollment flow. Constitutes the documentary evidence of the bilateral contract between the principal and TrustLayer Foundation under applicable electronic-signature law (Mexico CCF Art. 1834-bis, EU eIDAS Regulation 910/2014, US E-SIGN Act / UETA, UK Electronic Communications Act 2000, and equivalents). Does NOT duplicate or replace the authoritative audit log; it surfaces the legally-relevant facts (terms version, privacy version, attestation timestamp) in-band so verifiers can resolve them without registry round-trips."
+        }
+      },
+      "additionalProperties": false,
+      "description": "The subject of the credential \u2014 the AI agent and its attributes, including the holder verification key required for proof-of-possession and the enrollment attestation establishing the legal frame of issuance."
+    },
+    "proof": {
+      "type": "object",
+      "required": [
+        "type",
+        "cryptosuite",
+        "created",
+        "proofPurpose",
+        "verificationMethod",
+        "proofValue"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "DataIntegrityProof",
+          "description": "W3C Data Integrity proof type."
+        },
+        "cryptosuite": {
+          "type": "string",
+          "const": "mldsa65-ed25519-2026",
+          "description": "Composite cryptographic suite: ML-DSA-65 (post-quantum, FIPS 204) + Ed25519 (classical)."
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 datetime when the proof was created."
+        },
+        "proofPurpose": {
+          "type": "string",
+          "const": "assertionMethod",
+          "description": "The purpose of the proof. Always 'assertionMethod' for AID issuance."
+        },
+        "verificationMethod": {
+          "type": "string",
+          "pattern": "^did:aria:.+#.+$",
+          "description": "DID URL of the verification key used to create the proof."
+        },
+        "proofValue": {
+          "type": "string",
+          "description": "Composite signature (ML-DSA-65 + Ed25519) over the canonicalized credential (with proof stripped), as multibase base64url: the prefix \"u\" then unpadded base64url of u32be(pq_len) then the ML-DSA-65 signature then the Ed25519 one. The VC v2 context types this property as sec:multibase, so the prefix is part of the value. Credentials issued before the 1.0 cutover carry the same bytes with no prefix and remain valid; a verifier accepts both and decides between them by the length header, not the first character. Critically, the signature covers credentialSubject.holderKey, which is what stops anyone but the registry substituting a key.",
+          "pattern": "^u?[A-Za-z0-9_-]+$"
+        }
+      },
+      "additionalProperties": false,
+      "description": "W3C Data Integrity proof containing the composite post-quantum + classical signature."
+    }
+  },
+  "additionalProperties": false,
+  "_comment": "Illustrative and normative for shape only. The legalName rule above is enforced at issuance, not by this file. Credentials issued before the cutover declare their own spec_version and validate against the schema they were issued under; see schema/aid-v1.2.json.",
+  "_status": "DRAFT until the issuance cutover. No credential declares spec_version 1.0 yet, and the Verification Requirements this shape serves are still v1.3-draft, pending adoption by TrustLayer Foundation with ten decisions open. Fields already planned \u2014 a designated successor principal among them \u2014 have no place here. Because credentialSubject declares additionalProperties false, adding one later means a new schema file and a new spec_version, so this file is published to be reviewed and implemented against, not to be frozen. It freezes on the day the first credential declares 1.0."
+}