PlatformIdentityCredential — Mentionable v0.2

Status: Draft v0.2. Profile / capability URI: https://mentionable.dev/ns/identity/v0.2 JSON-LD context URL: https://mentionable.dev/ns/identity/v0.2/context.jsonld Supersedes for new issuance: the custom IdentityEvidence signed-attestation wire format (identity-evidence-v0.1.md, legacy URI https://mentionable.dev/ns/identity/v0.1). Last updated: 2026-09-03

This document defines the Mentionable profile of W3C Verifiable Credentials 2.0 used to carry recipient-bound, request-bound platform identity assertions from a Connector to a receiving agent. A PlatformIdentityCredential is a signed statement of fact (“this Slack workspace member sent this turn”, “this platform entity was observed mentioning this agent”), never an authorization or delegation by itself.

This profile replaces the custom envelope, signed-attestation proof, Connector Card key discovery, and new issuance under metadata.mentionable.identity_evidence described in identity-evidence-v0.1.md and issue #462. It preserves #462’s platform-observed invocation semantics and the PolicyPart/authorization boundary unchanged.

1. Purpose and design split

The v0.1 IdentityEvidence envelope defined its own issuer, subject, validity, audience, and proof structure, plus a bespoke RFC 8785 (JCS) + Ed25519 signature rule. All of that semantics already exists in maintained W3C standards:

• VC Data Model 2.0 — issuer, subject, validity window, credential typing.
• VC Data Integrity 1.0 — proof envelope, proofPurpose, domain (recipient binding), challenge (request binding).
• Data Integrity EdDSA Cryptosuites v1.0 — eddsa-jcs-2022 standardizes exactly the JCS + EdDSA combination the custom proof used.

v0.2 therefore keeps the Mentionable-specific parts — the claim vocabulary, canonicalization, carrier, trust policy, and TTL/replay profile — and delegates envelope and cryptography to the standards above.

The responsibility boundary from v0.1 is unchanged:

• Connector (issuer) verifies the native platform (Slack request signing, OAuth, etc.) and issues a short-lived credential bound to the receiving agent and to the enclosing request.
• Core defines structural parsing, the trust boundary between unverified and verified credentials, metadata carriers, and canonicalization.
• Agent/runtime policy decides which issuers, methods, and assurance levels are acceptable for a purpose. A cryptographically valid credential from an untrusted issuer is worth nothing.

Core MUST NOT keep a closed enum of identity methods (§7).

2. Versioning and published resources

Three URIs with distinct roles. They MUST NOT be conflated:

The HTML profile page is NEVER used as a JSON-LD @context. A credential’s @context MUST begin with exactly this ordered pair:

["https://www.w3.org/ns/credentials/v2", "https://mentionable.dev/ns/identity/v0.2/context.jsonld"]

Additional contexts MAY follow, but receivers only need to understand the two above.

3. Credential shape

A PlatformIdentityCredential is a VC 2.0 credential with:

• type including both VerifiableCredential and PlatformIdentityCredential.
• id — a unique identifier for this credential/observation event. The reference issuer uses a non-dereferenceable urn:uuid:<uuid> (§4).
• issuer — the Connector’s stable issuer identifier (§11).
• validFrom / validUntil — VC 2.0 validity terms replacing v0.1 issued_at / expires_at, subject to the TTL profile in §9.2.
• credentialSubject — the assertion about the immediate principal (§3.3).
• proof — an embedded Data Integrity proof (§9).

There is no credentialStatus. This profile uses short TTLs instead of revocation infrastructure (§9.2).

3.1 Example — direct Slack user

Issued when the Slack Connector verified (via Slack request signing) that a workspace member sent the current turn:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://mentionable.dev/ns/identity/v0.2/context.jsonld"
  ],
  "id": "urn:uuid:0d6f5f1e-8f3a-4a2e-9d38-6a4c8d1a9b21",
  "type": ["VerifiableCredential", "PlatformIdentityCredential"],
  "issuer": "did:web:slack-connector.example.com",
  "validFrom": "2026-08-19T12:00:00Z",
  "validUntil": "2026-08-19T12:05:00Z",
  "credentialSubject": {
    "id": "slack:T0123456/U0456789",
    "method": "urn:mentionable:auth:slack-workspace-member:v0.1",
    "assurance": "platform",
    "platform": {
      "provider": "slack",
      "workspace_id": "T0123456"
    },
    "profile": {
      "display_name": "JC",
      "username": "jc",
      "avatar": { "url": "https://avatars.slack-edge.com/T0123456-U0456789-abc123" },
      "locale": "ko-KR",
      "timezone": "Asia/Seoul"
    },
    "source": {
      "connector": "slack-connector.example.com",
      "channel": "C0987654"
    }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-08-19T12:00:00Z",
    "verificationMethod": "did:web:slack-connector.example.com#key-2026-08",
    "proofPurpose": "assertionMethod",
    "domain": "@travel@agents.example.com",
    "challenge": "9f4b6c2e-1d3a-4c5b-8e7f-2a1b3c4d5e6f",
    "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
  }
}

3.2 Example — platform-observed relay

Issued when the Connector did not verify the ultimate human, but observed a platform entity (typically another bot/app user relaying on someone’s behalf) mention the target agent in a platform context. The immediate principal is the observed platform entity, not the upstream human:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://mentionable.dev/ns/identity/v0.2/context.jsonld"
  ],
  "id": "urn:uuid:7c2e9b40-51df-4f6a-b1a3-9e8d0c2f4a55",
  "type": ["VerifiableCredential", "PlatformIdentityCredential"],
  "issuer": "did:web:slack-connector.example.com",
  "validFrom": "2026-08-19T12:00:00Z",
  "validUntil": "2026-08-19T12:05:00Z",
  "credentialSubject": {
    "id": "slack:T0123456/U0BOTUSER",
    "method": "urn:mentionable:auth:platform-mention:v0.1",
    "assurance": "platform",
    "platform": {
      "provider": "slack",
      "workspace_id": "T0123456"
    },
    "observedInvocation": {
      "target": "acct:travel@agents.example.com",
      "channel": "C0987654",
      "thread": "1755603600.000200",
      "message": "1755603601.000300"
    },
    "source": {
      "connector": "slack-connector.example.com",
      "channel": "C0987654"
    }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-08-19T12:00:00Z",
    "verificationMethod": "did:web:slack-connector.example.com#key-2026-08",
    "proofPurpose": "assertionMethod",
    "domain": "@travel@agents.example.com",
    "challenge": "3a7d1e88-6b2c-4f90-a5d4-c1e2f3a4b5c6",
    "proofValue": "z3FXQoLXtCUainYmNyxvB9pYlmYVpJv7qApC8QdGKmwLXY6PjfMS3jTMEfEgLrX2wA5nQpVKd6xB1cRzHqUvT9y2m"
  }
}

3.3 credentialSubject

credentialSubject is always an assertion about the immediate principal — the entity the Connector actually verified or observed. It never asserts upstream/downstream authority (§8).

type PlatformIdentityCredentialSubject = {
  id: string // canonical principal URL (§5) — never a raw @local@domain string
  method: string // open method token (§7)
  assurance: string // e.g. 'platform'; interpreted with issuer + method
  platform?: {
    provider: string // e.g. 'slack'
    workspace_id?: string
    [key: string]: unknown
  }
  observedInvocation?: {
    target: string // canonical URL of the mentioned agent (e.g. acct:travel@agents.example.com)
    channel?: string
    thread?: string
    message?: string
  }
  profile?: SenderProfileLike // presentation-only facts (§8); shape follows normalized-message.md SenderProfile
  source?: {
    transport?: string
    transport_module?: string
    connector?: string
    channel?: string
    thread?: string
    [key: string]: unknown
  }
}

observedInvocation means: the issuer observed the principal identified by credentialSubject.id mention observedInvocation.target in the given platform context. It is an observation record, not a delegation.

Credentials MUST NOT contain secrets: no Slack tokens, no raw provider objects, no private URLs, and no personal data beyond the whitelisted presentation fields.

4. Identifier semantics

Three identifiers in a credential are distinct values with distinct roles. Implementations MUST NOT substitute one for another:

Additionally proof.domain is the recipient binding — the canonical receiving agent address — and is unrelated to all three above.

5. Principal canonicalization

credentialSubject.id (and observedInvocation.target) MUST be a URL. Canonicalization rules:

A raw @local@domain string MUST NOT appear as credentialSubject.id. Internal normalized models that require the Mentionable display form MAY project acct:local@domain back to @local@domain; that projection is a presentation concern, never a wire concern.

Note the deliberate asymmetry: proof.domain uses the display form @local@domain (it is an audience string matched exactly against the receiver’s canonical address, mirroring v0.1 audience), while subject and target identifiers are URLs.

6. Mapping from IdentityEvidence v0.1

Semantic mapping from the legacy envelope. This is the normative translation table for migration tooling and mental models — not a bidirectional codec; new issuance uses the v0.2 shape natively.

7. Methods

The VC envelope is shared; identity method semantics are not merged. Two methods are defined by this profile:

The method set is open — core MUST NOT restrict it to a closed enum. New Connectors mint new method URIs without changing core. Unknown method values MAY be structurally preserved, but a method the receiver’s policy does not explicitly understand and allow MUST NOT be used as an authorization input.

8. Claim classes and the authorization boundary

A credential is a signed assertion of fact. It grants no authorization or delegation by itself. Only after signature, proof purpose, issuer trust, domain, challenge, validity, and replay checks all pass (§13) may it become an input to receiver-local policy.

Claims fall into three classes:

• Policy-eligible — method, assurance, platform.provider, platform.workspace_id, the verified principal (credentialSubject.id), and the observed target (observedInvocation.target).
• Presentation-only — profile fields: display name, username, avatar, locale, timezone. For attribution and UI rendering only.
• Diagnostic-only — channel/thread/message identifiers and source. For debugging and observability only.

Presentation-only and diagnostic-only claims MUST NOT be used for payment, account linking, destructive actions, delegation, rate-limit identity, or allowlist keys.

Receivers MUST NOT auto-generate on_behalf_of (or any delegation chain) from a PlatformIdentityCredential. Downstream authority of the original platform user is never claimed without a separate, explicit consent/delegation flow (PolicyPart step-up per policy-part-v0.1.md).

9. Proof requirements and TTL profile

9.1 Data Integrity proof

The single supported proof mechanism is an embedded Data Integrity proof. VC-JOSE-COSE, SD-JWT, and selective disclosure are out of scope for v0.2.

Normative requirements:

• proof.type MUST be DataIntegrityProof.
• proof.cryptosuite MUST be eddsa-jcs-2022 (vc-di-eddsa; JCS per RFC 8785). No other cryptosuite is accepted in v0.2.
• proof.proofPurpose MUST be assertionMethod.
• proof.domain MUST exactly match the canonical receiving agent address in @local@domain form. Receivers compare against their own canonical address; any mismatch is a hard rejection. No wildcards.
• proof.challenge MUST exactly match the messageId of the outer A2A message that carries the credential (§12). The JSON-RPC request id is a transport-correlation value and is NOT the challenge.

Issuance ordering: the Connector MUST fix the A2A message.messageId before creating the proof, put that value in proof.challenge, and send the credential inside the outer message bearing that same messageId. proof.domain MUST be re-bound to the final receiving agent on every issuance — credentials are never reused across recipients.

9.2 TTL profile

This profile uses short validity windows instead of credentialStatus / revocation:

Receivers MUST reject credentials whose validity window exceeds the maximum TTL, whose validFrom is in the future beyond the skew allowance, or whose validUntil is in the past beyond the skew allowance. Both validFrom and validUntil are required by this profile.

10. Replay contract

challenge == message.messageId verification alone does NOT prevent replay: an attacker who captures the entire outer A2A message can re-send it intact, and the challenge will still match. The binding narrows replay to whole-message re-submission within the validity window; it does not eliminate it.

Therefore:

• Receivers that maintain a replay cache MUST record the (issuer, domain, challenge) tuple for at least the credential’s validity window (plus skew) and MUST reject any second use of the same tuple. Such receivers provide request binding and one-time replay rejection.
• Receivers without a replay cache provide only short-TTL request binding. They MUST NOT claim replay safety, and deployments MUST NOT describe messageId binding by itself as replay prevention.

The conformance fixtures (§14) include a replay scenario: the second presentation of the same (issuer, domain, challenge) tuple is accepted by a cache-less verifier (with a documented “no replay protection” posture) and rejected by a caching verifier.

11. Issuer trust and key resolution

11.1 Trust policy before any fetch

Issuer trust is receiver-local policy. A valid signature proves only control of a key — it does not make the issuer trustworthy, and there are no built-in or hard-coded trusted Connector issuers.

The order of operations is fixed (SSRF mitigation):

1. The receiver checks that the credential’s exact issuer identifier is pre-registered in its local issuer trust policy. If not, the credential is rejected without any network fetch. Caller-provided issuer strings never cause a fetch on their own.
2. Only for a trusted issuer does the receiver resolve verification material (DID document or HTTPS controlled identifier document).
3. After the signature verifies, the receiver MUST confirm that proof.verificationMethod is actually listed under the issuer/controller’s assertionMethod relation. A key that merely appears in the document (or in an unrelated relation) is an issuer/controller mismatch and a hard rejection, regardless of signature validity.

11.2 Issuer identifier forms

The generic profile accepts:

• HTTPS controlled identifiers — an https:// URL whose controlled identifier document publishes assertionMethod verification methods.
• DIDs — any DID method the receiver’s resolver supports, subject to the same trust-policy-before-fetch rule.

The Slack reference issuer uses did:web:<connector-host> as its canonical issuer identifier. It publishes a DID document at https://<connector-host>/.well-known/did.json containing rotating assertionMethod Multikey (Ed25519) keys. Their ids remain did:web:<connector-host>#<kid>. The same DID document MAY contain additional verification methods for orthogonal protocols. In particular, the Slack reference Connector’s OAuth federation integration publishes the same public material in a distinct JsonWebKey method at #<kid>-oauth-jwk; its v0.2 proofs continue to reference the unsuffixed Multikey. A verification method MUST NOT combine publicKeyMultibase and publicKeyJwk, as prohibited by DID Core. Key rotation is expressed by updating both representations in the DID document; verifiers re-resolve subject to their cache policy (§11.3).

11.3 Key-fetch hardening

When fetching a DID document or controlled identifier document, receivers MUST:

• accept https: only — reject other schemes, and reject loopback, link-local, and private-range hosts in production;
• enforce a response size limit (reference: 64 KiB) and a fetch timeout (reference: 5 seconds);
• cache resolved documents with a bounded TTL (reference: 5 minutes, honoring shorter HTTP cache directives) so rotation propagates quickly while hot paths avoid per-message fetches;
• on signature failure with a cached document, optionally re-fetch once (rotation may have occurred) before rejecting.

11.4 No automatic promotion of legacy trust entries

Legacy v0.1 deployments keyed their Trusted Connector Issuer policy by Connector hostname. Those entries MUST NOT be auto-promoted to did:web issuer trust: did:web:host is a different exact identifier with a different resolution path. Operators migrating to v0.2 pin the new exact issuer identifier explicitly (§16).

12. A2A carrier and capability negotiation

12.1 Carrier

The v0.2 carrier is:

{
  "message": {
    "messageId": "9f4b6c2e-1d3a-4c5b-8e7f-2a1b3c4d5e6f",
    "metadata": {
      "mentionable": {
        "verifiable_credentials": [
          /* PlatformIdentityCredential objects with embedded Data Integrity proof */
        ]
      }
    }
  }
}

metadata.mentionable.verifiable_credentials is an array of VC JSON objects, each carrying its embedded proof. Every credential’s proof.challenge MUST equal the enclosing message.messageId.

12.2 Capability negotiation

Receiving agents advertise v0.2 support by declaring the extension URI https://mentionable.dev/ns/identity/v0.2 in a2a.capabilities.extensions[] on their Agent Card (see agent-card.md §1.2).

Issuers (Connectors) send both direct-user and platform-observed-relay credentials via the v0.2 carrier to any v0.2-capable recipient.

Extension URI matching is exact string comparison. There is no trailing slash tolerance, no case normalization, and no scheme or version coercion: https://mentionable.dev/ns/identity/v0.2/ and https://Mentionable.dev/ns/identity/v0.2 are both non-matches. Agent Cards MUST advertise the URI verbatim as written above, and issuers MUST NOT normalize before comparing — an unclear capability signal falls under §12.3 (fail closed), not under a lenient match.

12.3 v0.1 fallback rules

• The legacy carrier metadata.mentionable.identity_evidence remains only as an explicitly-gated fallback for v0.1-only recipients during the compatibility window.
• The same credential fact MUST NOT be placed in both carriers at once.
• If the recipient’s capability is absent or unclear, the issuer MUST fail closed (send no identity assertion) or use only the explicitly documented and explicitly configured v0.1 fallback. Capability ambiguity never silently downgrades to the legacy path.

Receivers treat both carriers as caller-controlled input: structural validity alone never promotes an entry to trusted identity (§13).

Transport scope. §12 covers the A2A carrier only. The REST transport’s Mentionable-Identity-Evidence header stays v0.1-only in this revision: it carries signed IdentityEvidence and MUST NOT carry a PlatformIdentityCredential. A future revision may define a REST carrier for v0.2 credentials (header size and the request-binding equivalent of proof.challenge are the open questions); until then, REST callers that need v0.2 semantics use A2A.

13. Core trust boundary

@mentionable/core separates structural parsing from security verification at the type level:

unknown metadata
  → structural parse → UnverifiedPlatformIdentityCredential
  → verification: signature + proofPurpose + issuer trust
    + issuer/controller (assertionMethod) + domain + challenge
    + validity window + replay policy
  → VerifiedPlatformIdentityCredential
  → internal identity (sender.identities / caller.presented)

• The structural parser returns UnverifiedPlatformIdentityCredential and nothing stronger. Structurally valid credentials MUST NOT be normalized into sender.identities, caller.presented, or any authorization input.
• VerifiedPlatformIdentityCredential is a separate result type (branded boundary) that only a verifier which has passed all security checks can produce.
• Internal normalization helpers accept only verified results as input.
• Implementations MUST NOT hand-roll Data Integrity cryptography. Use a maintained conformant stack and validate against the official W3C test vectors. Informative reference stack: @digitalbazaar/vc, @digitalbazaar/data-integrity, @digitalbazaar/eddsa-jcs-2022-cryptosuite, @digitalbazaar/ed25519-multikey; official vectors at https://github.com/w3c/vc-di-eddsa/tree/main/TestVectors.

14. Conformance fixtures

Versioned profile fixtures live in-repo at fixtures/platform-identity-credential/v0.2/, usable by external implementations without depending on Mentionable packages or source. The fixture set covers:

• Positive: a valid direct-user credential (slack-workspace-member) and a valid platform-mention relay credential.
• Negative: wrong domain; challenge/messageId mismatch; expired; not-yet-valid; malformed @context/type; tampered payload/signature; issuer/controller mismatch (verificationMethod not under the issuer’s assertionMethod).
• Replay scenario: a described sequence where the second use of the same (issuer, domain, challenge) tuple must be rejected by a replay-cache-equipped verifier.
• A test keypair (and matching DID document material) so verifiers can run the suite offline.

15. Security considerations

• Fact, not authority. A verified credential is evidence for policy, never authorization, delegation, or consent by itself (§8).
• Trust before fetch. Never resolve keys for an issuer that is not already pinned in local policy (§11.1). This is the primary SSRF defense.
• Signature ≠ trust. Signature verification, issuer trust, and issuer/controller (assertionMethod) checks are three separate gates; all are required.
• Exact bindings. domain and challenge matching is exact-string. Canonicalize the receiving address before comparison.
• Replay honesty. Do not describe messageId binding as replay prevention. Only a (issuer, domain, challenge) replay cache provides one-time semantics (§10).
• No token substitution across versions. v0.1 and v0.2 capabilities, carriers, and validation paths are distinct; a v0.1 envelope is never accepted on the v0.2 path or vice versa.
• Data minimization. No secrets, tokens, raw provider objects, private URLs, or unnecessary personal data in credentials. Profile fields are a whitelist.
• Short-lived by design. No credentialStatus; the TTL profile (§9.2) bounds exposure. Do not extend TTLs to “make caching easier”.

16. Migration from v0.1

For issuers (Connectors):

1. Detect recipient capability via the Agent Card extension URI (§12.2).
2. Issue PlatformIdentityCredential via metadata.mentionable.verifiable_credentials to v0.2-capable recipients; keep the v0.1 identity_evidence carrier only behind an explicit compatibility gate (§12.3).
3. Stop new signed-attestation issuance on the v0.2 path entirely.

For receivers (operators):

1. Advertise https://mentionable.dev/ns/identity/v0.2 once the verifier is deployed.
2. Pin the new issuer explicitly. A legacy hostname trust entry (e.g. slack-connector.example.com for Connector Card discovery) is NOT automatically valid for v0.2. Add the exact new issuer identifier — for the Slack reference issuer, did:web:slack-connector.example.com — to the local issuer trust policy as a deliberate operator action (§11.4).
3. Decide the replay posture (§10) and document it.
4. Keep accepting v0.1 evidence during the compatibility window if needed; the semantic mapping in §6 relates the two shapes.

Relationship to issue #462: the platform-observed invocation semantics and the PolicyPart/authorization boundary defined there are preserved intact. #462’s custom envelope, signed-attestation proof, Connector Card key discovery, and new identity_evidence issuance procedure are superseded by this profile.

17. References

Normative:

• W3C Verifiable Credentials Data Model 2.0
• W3C Verifiable Credential Data Integrity 1.0
• W3C Data Integrity EdDSA Cryptosuites v1.0 (W3C Recommendation, 2025-05-15)
• W3C DID Core
• W3C Controlled Identifiers v1.0
• did:web method
• RFC 8785 — JSON Canonicalization Scheme (JCS)

Informative:

• identity-evidence-v0.1.md — legacy envelope and carrier.
• agent-card.md — capability advertisement.
• normalized-message.md — sender.identities surface.
• policy-part-v0.1.md — step-up for consent/delegation.
• Reference implementation stack: @digitalbazaar/vc, @digitalbazaar/data-integrity, @digitalbazaar/eddsa-jcs-2022-cryptosuite, @digitalbazaar/ed25519-multikey.